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