> For the complete documentation index, see [llms.txt](https://docs.nullify.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.nullify.ai/configuration/configuration-pull-requests.md).

# Repository Scans

## Overview

**Settings → Repository scans** (or the PR settings API) controls whether Nullify scans pull requests and pushes automatically, and how Nullify's check and reviews behave on each pull request: which findings fail the check, what priority of finding is severe enough to count, and whether Nullify reviews the pull request at all.

These settings are tenant-wide — they apply to every connected repository — and require the **config:write** permission to change. They map directly to the admin API (`PUT /admin/pr-gate-settings`), so the same behaviour can be automated.

## The Nullify check

Nullify reports a single check named **Nullify** on every pull request, covering code (SAST), dependency (SCA), container, secrets and supply-chain analysis together. The check has three outcomes: **failed** (blocks a required check), **neutral** (Nullify could not finish checking the change; satisfies a required check without claiming the change is clean), and **passed**.

By default the check is **information only**: it reports findings on the pull request and findings never fail it. Three independent findings controls turn it into a gate, and you can combine them.

| Control                                                                                       | API field            | Fails the check when                                                                                                                                  |
| --------------------------------------------------------------------------------------------- | -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| [Findings that fail the check](#findings-that-fail-the-check)                                 | `findingsPolicy`     | The pull request introduces a finding the chosen policy blocks on.                                                                                    |
| [Always block new CVEs at or above the cutoff](#always-block-new-cves-at-or-above-the-cutoff) | `cvssEnforcement`    | The pull request introduces a dependency or container CVE at or above the CVSS cutoff, regardless of AI triage, whether it has not run or disagrees.  |
| [Always block new true-positive secrets](#always-block-new-true-positive-secrets)             | `secretsEnforcement` | The pull request introduces a credential triaged Low priority or above, verified or not, regardless of the findings policy and the blocking priority. |

With every control off, findings never fail the check; its summary still lists them. A scan that could not complete never fails the check under any setting; see [Incomplete scans](#incomplete-scans).

{% hint style="info" %}
Failing the check does not block the merge on its own. To turn it into a hard merge requirement, mark the **Nullify** check as required in your provider's branch-protection / merge-check rules (for example, GitHub branch protection's "Require status checks to pass").
{% endhint %}

## Settings

<figure><picture><source srcset="https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-b54defa8ec284b4803154df9535e8c3871d7aec4%2Frepository-scans-settings-dark.png?alt=media" media="(prefers-color-scheme: dark)"><img src="https://3946391995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FId2OtLCL6O6V3XSRYxtr%2Fuploads%2Fgit-blob-b49fc837509310b4fd03cf70b13ec9eaf6e80b3d%2Frepository-scans-settings.png?alt=media" alt="Repository scans settings"></picture><figcaption><p>Automatic scans, the Nullify check and PR reviews.</p></figcaption></figure>

### Automatic scans

**Pull request scans** and **Push scans** are on by default. With **Pull request scans** off, Nullify does not automatically scan new pull request commits and posts no **Nullify** check or review for them. With **Push scans** off, it does not automatically scan pushed commits, including secrets scans on every branch. Changes apply before the next automatic scan starts: a scan already running finishes, manual scans continue and existing reviews stay. Onboarding and scheduled scans are independent of both switches.

### Findings that fail the check

| Policy                      | API value   | Fails the check when                                                                                                                                                                                                                                                                                                                 |
| --------------------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| No findings block (default) | `none`      | Never, on findings alone.                                                                                                                                                                                                                                                                                                            |
| Confirmed new findings      | `confirmed` | The pull request introduces a code, dependency, container or secret vulnerability that AI triage confirmed at or above the [blocking priority](#blocking-priority), or an enforced supply-chain policy finding at or above it. A finding that has not been triaged, or whose triage failed, never fails the check under this policy. |

The earlier values `net_new` and `triaged_confirmed` no longer exist; the API rejects them with `400`. Gates saved before this change were moved automatically: an enabled gate became `confirmed`, a disabled gate became `none`.

Pushes never fail the check under any policy.

The gate evaluates **net-new findings only**: issues this pull request introduces relative to its target branch. Pre-existing findings never fail an unrelated pull request, so turning a policy on does not block in-flight work retroactively.

If Nullify could not compare the pull request against its target branch, findings above the threshold conclude the check **neutral** rather than failing it, because Nullify cannot confirm the pull request introduced them.

### Always block new CVEs at or above the cutoff

Off by default. When on, the check fails on any pull request that introduces a dependency or container CVE with a CVSS score at or above the cutoff, regardless of AI triage. The cutoff defaults to **9.0**; set another value from 0 to 10 in the **CVSS cutoff** field or with `scaBlockCvssThreshold`.

* Only a CVE the pull request introduces counts, so Nullify needs its comparison against the target branch. Without it, a CVE at or above the cutoff leaves the check **neutral**.
* Only allowlisting, archiving or a manual priority override (including marking it a false positive yourself) exempts a finding. An AI priority or an AI false-positive verdict does not, because this rule applies regardless of triage.
* Pushes never fail on this rule.

When off, a CVE's CVSS score never fails the check on its own: under **Confirmed new findings** it still needs AI confirmation.

### Always block new true-positive secrets

Off by default. When on, the check fails on any pull request that introduces a credential triaged Low priority or above, whether or not it was verified, regardless of the findings policy and the blocking priority.

* Allowlisted and false-positive secrets are exempt, and so are dead or revoked credentials triaged Negligible.
* Pushes never fail on this rule.

### Incomplete scans

The dashboard shows **Incomplete scan or review** as **Neutral**: a scan that could not complete after its recovery attempts never fails the check. It concludes the check **neutral**, with a note in the check summary, whichever controls are on. A scanner that is not enabled, is outside your scan scope or has no changed input to scan does not count as incomplete. If Nullify cannot read your gate settings and has no record of them from when the scan started, the check also concludes neutral.

Neutral satisfies a required check, so read the check summary for any stage that did not finish. On Azure DevOps, where a status policy accepts a neutral status, an incomplete review is reported as an error instead, which holds the merge, whenever a findings control (or the legacy `failOnIncompleteCoverage` API field) is on.

### Blocking priority

Sets the lowest finding priority that counts, for the **Confirmed new findings** policy and for change requests:

* **Urgent** — only `URGENT` findings count.
* **Urgent + Important** — both `URGENT` and `IMPORTANT` findings count.

Lower-priority findings (`MEDIUM` and below) are always reported but never fail the check through the findings policy. The CVSS and secrets rules apply their own thresholds.

### PR reviews

When on (the default), Nullify reviews the pull requests it scans: inline comments on findings, a review summary and, when allowed below, an approving or a request-changes review. When off, Nullify posts no review on any pull request and the two settings below do nothing. The next time Nullify scans a pull request after you turn reviews off, it dismisses its own outstanding request-changes reviews on it, so a stale Nullify review does not keep blocking the merge; reviews from people are never touched. If Nullify cannot read this setting, or Nullify pauses reviews platform-wide, it posts no review and dismisses nothing. The **Nullify** check is unaffected either way.

When Nullify has a concrete security concern about code the pull request introduced or changed, it posts a review. A pull request with no security concern receives no review comment at all; the passing **Nullify** check is the all-clear signal.

### Clean pull request

The dashboard offers only **No review**: Nullify never submits an approving review, and a clean pull request is left without a review.

The API field `allowApprovingReviews` (off by default) still lets Nullify submit an **approving** review on a pull request with no blocking findings, and only when every scanner finished. Because a bot approval can satisfy a required-reviewer rule, this is opt-in. Saving the settings from the dashboard turns it off.

{% hint style="warning" %}
Approving reviews mean a Nullify approval can count toward a required-reviewer rule on your branch protection. Leave this off if you want every pull request to still require a human approver.
{% endhint %}

### Security concerns

* **Comment (default)** — Nullify raises concerns at or above the blocking priority as **comments**.
* **Request changes** — Nullify submits a **request-changes** review for them. Because a request-changes review can block a merge under branch protection, this is opt-in.

{% hint style="info" %}
The review verdict and the **Nullify** check are independent. The check's outcome comes only from the gate controls and the blocking priority; a *request changes* review does not by itself fail the check, and a failing check does not depend on the review verdict.
{% endhint %}

## Merge overrides

An Admin can clear a Nullify blocker on a single pull request without changing these settings, for example during a scanner outage. Overrides need the **config:write** permission, which the **Admin** role grants. The controls are under **Assessments → Code reviews**; see [Code reviews in the dashboard](https://docs.nullify.ai/capabilities/code-reviews.md#code-reviews-in-the-dashboard).

An override does not resolve or change any finding. Human reviews and branch protection still apply. A later scan of the pull request re-evaluates the check and can block it again.

### Mark a check as passing

Select **Mark as passing** on a review's **Merge controls**, on **Pull request blockers** or on **Pipelines**, or select **Override** on **Check runs**. It is offered for a Nullify check that is failing, errored or incomplete, including a check still running two hours after it started. A reason is optional, up to 1,000 characters. Nullify completes the check as passing. The check description on your git platform names who overrode it and gives the reason, when the platform's description limit allows.

A check that Nullify cannot match to one of its scanners shows **Not overridable**. Resolve it on your git platform instead.

To override several at once, select pull requests on **Pull request blockers**, or select every overridable pull request on the page, then select **Mark as passing**. A bulk override needs a reason, which applies to every check. Each check succeeds or fails on its own, and the dialog then lists how many succeeded and which failed.

### Withdraw Nullify change requests

When Nullify's **Request changes** review is blocking a pull request, open the review from **Runs** or **Pull request blockers**. Under **Merge controls**, select **Withdraw Nullify change requests** and give a reason of up to 1,000 characters. Nullify dismisses its own blocking reviews on the commit; reviews from people stay. This does not approve the pull request. Withdrawal works one pull request at a time, only on the open pull request's current head commit, and only where your git provider supports dismissing reviews.

### Audit

Each override and withdrawal is written to Nullify's audit log with your name and reason. If the audit record cannot be saved, the dashboard says so. The API equivalent of marking a check as passing is [Override a check run](https://docs.nullify.ai/api-reference/api-reference/orchestrator.md#override-a-check-run).

## Equivalent API

| Setting                                      | API field                    | Values                                                                                            |
| -------------------------------------------- | ---------------------------- | ------------------------------------------------------------------------------------------------- |
| Pull request scans                           | `prScansEnabled`             | `true` / `false`; omitted keeps the stored value                                                  |
| Push scans                                   | `pushScansEnabled`           | `true` / `false`; omitted keeps the stored value                                                  |
| Findings that fail the check                 | `findingsPolicy`             | `none`, `confirmed`                                                                               |
| Always block new CVEs at or above the cutoff | `cvssEnforcement`            | `true` / `false`                                                                                  |
| CVSS cutoff                                  | `scaBlockCvssThreshold`      | Number from 0 to 10; omitted or null keeps the stored cutoff, and 9.0 applies when none is stored |
| Always block new true-positive secrets       | `secretsEnforcement`         | `true` / `false`; omitted keeps the stored value                                                  |
| Blocking priority                            | `minPriority`                | `URGENT`, `IMPORTANT`                                                                             |
| PR reviews                                   | `prReviewsEnabled`           | `true` / `false`                                                                                  |
| Clean pull request: Approve (API only)       | `allowApprovingReviews`      | `true` / `false`                                                                                  |
| Security concerns: Request changes           | `allowRequestChangesReviews` | `true` / `false`                                                                                  |

```http
PUT /admin/pr-gate-settings
{
  "prScansEnabled": true,
  "pushScansEnabled": true,
  "findingsPolicy": "confirmed",
  "cvssEnforcement": true,
  "secretsEnforcement": false,
  "enabled": true,
  "minPriority": "IMPORTANT",
  "prReviewsEnabled": true,
  "allowApprovingReviews": false,
  "allowRequestChangesReviews": false,
  "scaBlockCvssThreshold": 9.0
}
```

Tenants that have never saved the page get an information-only gate: `findingsPolicy` `none`, `cvssEnforcement` and `secretsEnforcement` false, `URGENT`, pull request scans, push scans and PR reviews on, and both review options off.

`findingsPolicy` and `cvssEnforcement` are authoritative for findings. `enabled` is kept for older clients: `GET` derives it (true when `findingsPolicy` is `confirmed` or `cvssEnforcement` is on; `secretsEnforcement` does not set it). A `PUT` that sends `findingsPolicy` must send a matching `enabled`, or it is rejected with `400`; `cvssEnforcement` is only accepted alongside `findingsPolicy`. A `PUT` without `findingsPolicy` turns the findings policy and CVSS enforcement off when `enabled` is false. When `enabled` is true it keeps the stored findings policy and CVSS enforcement, and uses `confirmed` if nothing else would block. `secretsEnforcement`, `prScansEnabled`, `pushScansEnabled` and `prReviewsEnabled` are independent of all of these: a `PUT` that sends one replaces the stored value, and one that omits it keeps it.

The legacy `failOnIncompleteCoverage` field is still accepted and stored, but a scan that could not complete never fails the check; saving from the dashboard sets it to `false`. Every settings change is written to the audit log with its previous and new values.

`PUT` replaces the settings. Read the current settings first and retain every value you intend to preserve: omitting `allowApprovingReviews` or `allowRequestChangesReviews` turns it off. Omitting `scaBlockCvssThreshold` keeps the stored cutoff; send `9.0` to restore the default. Supply-chain enforcement rules also affect gate results; `GET /admin/pr-gate-settings` returns the resolved `scpm` policy details. That response alone does not establish whether supply-chain detection is enabled for your tenant.
