Commands

Write @forseti followed by a command in a pull request comment. Forseti adds an eyes reaction to show it has the command, then acts. Commands are not case-sensitive, and one command is read per comment.

@forseti review deep

Command reference#

review#

@forseti review runs a review straight away of what changed since the last review, together with any files of the PR that an earlier review did not reach. Code that a review has already checked, including in other PRs, is not reviewed or charged again, unless it still has an open blocking or should-fix finding. If the latest commit already has a review, Forseti replies with that result and a link instead of running a second one, and charges nothing; if a review of it is still running, it says so. Use @forseti review full to review the whole PR again. It runs even on a PR the skip rules would pass over (drafts, bots, labels, paused). Two rules still hold: PRs that change only lockfiles, generated or vendored files, and forks when the workspace allows no fork reviews at all.

Add a depth for a one-off review at that depth. The check run shows the depth and the estimate as soon as it starts. If an owner has set a maximum depth for the workspace, a request above it runs at the maximum and the reply says so.

review rest#

One Glance, Standard or Deep review costs at most £2. On a large PR that is not enough for every file at full depth, so the summary names the files that had only a lighter pass or were not reviewed, and the verdict does not say clear. Later pushes carry on with those files, within your caps.

@forseti review rest finishes them in one review, at full depth and without the £2 ceiling. Forseti first replies with the number of files and the price, for example:

Price Guard: reviewing the 31 files not fully reviewed yet would cost about £3.80, and Forseti holds up to £4.60 before it runs. Reply @forseti confirm to run it.

Nothing runs until someone replies @forseti confirm, and the charge is never more than the amount held. Your per-PR and monthly caps still apply. The figures above are only an example.

confirm and Price Guard#

The per-PR cap is the total across all reviews of one pull request (£5 by default); each single review costs at most £2 (Molecular, early access, and @forseti review rest show their own price before they run). When a review would push the PR past its cap, Forseti does not run it. It replies with the estimate and the reason instead. For example, a Deep review on a PR that earlier reviews have already used £4.20 of:

Price Guard: a Deep review would cost about £1.60, and Forseti holds up to £2.00 before it runs. This PR has used £4.20 of its £5.00 cap, so the cap would be exceeded. Reply @forseti confirm to run it anyway (only the per-PR cap is waived; monthly caps still apply).

@forseti confirm runs that review once. It also confirms the price of review rest, which waives no cap: your per-PR and monthly caps still apply. It only works while that question is open on the latest push; after a new push, ask again. The figures above are only an example.

Replying to a finding, and reopen#

Reply in a finding's thread in your own words, for example “fixed in a1b2c3d” or “not a bug: this is checked in orders.ts:40”. Forseti looks at the finding again against the code at the latest commit, including the places your reply points to, and answers in the thread:

• Fixed in the commit, with one line on why, and it resolves the thread;
• Still open, with the reason;
• Withdrawn as not a fault, and it resolves the thread. The finding's share of the review comes back as credits, as for an “incorrect” dismissal.

Your reply is never taken as proof. “Mark this fixed” changes nothing unless the code shows it, and a blocking or security finding closes only when a second look, which does not see your reply, agrees. A second reply is judged again. Resolving the thread yourself also makes Forseti look again; if the finding is still there it says so in the thread once, and it never reopens your thread. Each push does the same for the open findings it could affect. These second looks are free, up to 20 replies and resolves per pull request per day.

@forseti reopen in a finding's thread reopens a finding Forseti marked fixed or withdrew, for example when you disagree; the dashboard's Reopen does the same. If it was withdrawn, its credit-back is taken back. The summary and the check update with no new review.

pause and resume#

@forseti pause stops automatic reviews on this one PR, for example while it is being reworked. Explicit @forseti review requests still run. @forseti resume turns automatic reviews back on. To stop reviews for a whole repo, switch it off in the dashboard or use branch targeting.

config#

@forseti config answers “why did Forseti do that?”. It replies with a table of every setting in force for this PR (depth, profile, inline cap, branches, ignored paths, dimensions, skip rules and caps), the value, and its source: a workspace lock, .forseti.yaml, the repo's settings, a policy rule, a workspace default or the product default. Any problem reading .forseti.yaml is listed too.

explain#

Reply @forseti explain inside a thread Forseti started on a finding. It reads the finding and the code around it at the latest push, and replies in the thread with a fuller explanation and the reasoning behind the fix. An explanation is a small charge in credits, shown before it runs. They are limited to 10 per PR per hour and 100 per workspace per day.

Used outside a finding thread, it points you to the threads.

ask#

@forseti ask followed by a question answers it in the same place: a reply in the thread when you ask inside a review thread, or a new comment on the PR. Answers are grounded in the diff and cite file and line.

@forseti ask why is this query not paged?

Asking is a small charge in credits, limited to 10 questions per PR per hour and 100 per workspace per day. Asking from the dashboard's PR page also keeps a history.

split#

When a pull request is large (by default over 800 reviewable lines or 25 files), the summary includes a collapsed proposal to split it into 2 to 4 ordered parts, grouped by import graph and directory, each with a title and a reason. @forseti split posts that proposal as a comment, working one out on demand if the PR is under the threshold. If the changes all sit in one area, it says so instead.

release-notes#

@forseti release-notes drafts user-facing notes from the repo's pull requests merged in the last 30 days (or from this PR), grouped into features, fixes and breaking changes, ready to paste. It is a small charge in credits and limited to 5 per PR per hour. For a specific range of refs, use the dashboard or the API.

Who can use commands#

Only people GitHub lists as an owner, member or collaborator of the repository can run commands. Comments from anyone else, and from bots, are ignored without a reply, so a stranger on a public repo cannot spend your credits. Every command, accepted or refused, is written to the workspace audit log.

Commands inside quoted lines (>) or fenced code blocks are ignored, so quoting a command never re-runs it.