Use
Commands
Drive Forseti from the pull request. Mention @forseti in a comment to re-review, change depth, pause, explain a finding or show the settings in force.
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 deepCommand reference
| Command | Where | What it does |
|---|---|---|
@forseti review | PR comment | Reviews the latest push at the depth configured for this PR. |
@forseti review glance | PR comment | One-off Glance review. quick is an alias. |
@forseti review standard | PR comment | One-off Standard review. |
@forseti review deep | PR comment | One-off Deep review. Above the per-PR cap, Forseti asks first with the price. |
@forseti review molecular | PR comment | Early access: runs Deep and says so on the PR. |
@forseti confirm | PR comment | Runs the Deep review that Price Guard asked about, once. |
@forseti pause | PR comment | Stops automatic reviews on this PR. |
@forseti resume | PR comment | Restarts automatic reviews on this PR. |
@forseti config | PR comment | Replies with the settings in force and where each one came from. |
@forseti explain | Reply in a Forseti finding thread | A longer explanation of that finding and its fix. Free. |
@forseti ask <question> | PR comment or thread | Answers a question about the PR, citing file and line. Free. |
@forseti split | PR comment | Proposes how to split a large PR into smaller, ordered parts. |
@forseti release-notes | PR comment | Drafts user-facing release notes for recently merged PRs, or this one. Free. |
@forseti help | PR comment | Lists the commands. An unknown command gets the same reply. |
review
@forseti review runs a review of the latest push straight away, 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.
confirm and Price Guard
When a Deep review would exceed the per-PR cap, Forseti does not run it. It replies with the estimate and the reason instead:
Price Guard: a Deep review would cost about £4.64 (up to £5.80), but the per-PR cap (500 credits) would be exceeded. Reply
@forseti confirmto run it anyway (only the per-PR cap is waived; monthly caps still apply).
@forseti confirm runs that review once. 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.
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. Explanations are free. 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 from GitHub is free, limited to 10 questions per PR per hour and 100 per workspace per day. Asking from the dashboard's PR page keeps a history and is metered as a small charge.
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 free 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.