Skip to main content

The score

Every complete review carries a safe-to-merge score between 0 and 1. A review is complete when every step of it finished and it took in the whole change. The review summary shows the score next to the plain verdict:
The score belongs to the exact commit that was reviewed. A review that covers every changed line it scores and leaves nothing open scores high. Only these lower it:
  • Open findings, by the severity the review shows. Any open High or Critical finding puts the score below 0.50. A Low finding lowers it a little.
  • Code the review does not cover, generated and vendored files included, in proportion to its share of the changed lines the score counts. See What the review does not cover.
  • Claims the review raised and did not publish. They were not ruled out, so they count for a little: each lowers the score by no more than one Low finding would, whatever severity the review agent gave it. A claim on a file outside the scored changes, such as a lockfile or a file the review agent created itself, does not lower it.
One exception keeps a known problem from passing: a finding Veridical verified but did not publish only because the pull request discussion already raises it, because Veridical could not read the discussion, or because it could not tell whether the discussion already raises it, keeps the severity it would have been shown. A comment that mentions a bug does not fix it, so a High finding the discussion already raises still puts the score below 0.50. The summary names what lowered the score, for example “2 claims the review raised and did not publish (each counted as Low)” or “1 finding not published because the pull request discussion already raises it (1 High)”. A complete review that covers every changed line it scores and leaves no open finding of Medium severity or above can reach 0.95. The score is advisory evidence, not a guarantee. A high score is not proof that the code has no defects.

What the review does not cover

Of the changed files the score counts, these count as not covered and lower the score:
  • a text change that GitHub shows without a diff because it is too large to show;
  • files the review’s size budget left out of a large pull request;
  • changed files missing from GitHub’s file list;
  • generated and vendored files, which Veridical does not review (see Generated and vendored files).
The summary says how many of each. With a threshold of 0.95, a pull request in which more than a small share of the scored changed lines is not covered cannot pass the gate, even with no open finding.

Generated and vendored files

Veridical recognizes generated and vendored code by signals such as its path, its file name and its header: code under a folder such as vendor/ or dist/, a name such as *.min.js, or a header that marks the file as generated. It does not review those files. The pull request itself can set every one of those signals, so their changed lines count as code the review does not cover and lower the score. The summary names them in their own line, for example:
A pull request that changes only such files scores near 0 and cannot pass the gate. If your repository commits generated or vendored files the gate should ignore, list them in path_filters in the settings file on the base branch. Files left out that way are not scored. If the line counts files you did not expect, look at them before you merge.

Files that are not scored

Some changed files are left out of the score altogether, so they never lower it:
  • lockfiles, such as package-lock.json or yarn.lock;
  • binary or empty files, such as images, in any folder;
  • files your path_filters leave out.
The summary names them in one line, for example:
A pull request made only of such files, such as a lockfile-only dependency update, is scored on the review’s findings alone, and the line says so.

Which reviews get no score

Only a complete review is scored. These get no score, never a low one, and the summary or the check says why:
  • a review that did not finish (see When a review does not complete);
  • a review that was posted with a gap: a step of it hit an error, it reached its time or spend limit, the context prepared for it could not hold the whole change, or it raised more claims than Veridical processes in one review;
  • an additional review that read only the newest commits without carrying the earlier findings forward;
  • a review whose pull request or repository changed while it ran, for example through a newer commit.

The merge gate

The gate is opt-in and off by default. A repository turns it on in its repository settings file, .veridical.yaml or .veridical.yml, at the repository root:
The threshold is a number greater than 0 and at most 1. Veridical reads the setting from the pull request’s base branch, so a pull request cannot change its own gate. When both files exist, only .veridical.yaml is read, and the review summary says so. A setting Veridical does not understand, such as another metric, > instead of >=, a threshold out of range, or extra keys, turns nothing on: no safe-to-merge check is posted, and the review summary says the setting was not understood.

The safe-to-merge check

With the gate on, Veridical posts a second check run named safe-to-merge on the exact head commit it reviewed. Its title gives the reason in one line. success is the only passing result. When Veridical does not review a commit at all, its safe-to-merge check is failing or missing; a required check that is missing also keeps the merge blocked on GitHub. To block merges with it, make safe-to-merge a required status check in your branch protection rule or ruleset on GitHub. Veridical never approves or merges a pull request. The gate only reports a pass or a fail; your branch protection decides what that means, and anyone who can bypass branch protection still can.

After new commits

The check belongs to the reviewed commit. A new commit has no safe-to-merge check until Veridical reviews it, and after a completed review new commits do not start a review on their own, so a required check holds the merge until a maintainer asks for a fresh review of the new head:
  • For a scored review, comment /veridical review, which reviews the whole pull request again at its new head.
  • /veridical additional-review reviews only the commits since the last completed review. Unless it carries the earlier findings forward, it gets no score and the check fails; its summary says which.
See Commands. Without the auto_merge key nothing changes: each review posts one neutral advisory check run, Veridical Review (advisory), which never blocks a merge.
Last modified on November 17, 2026