Policies & depth

The four depths#

Depth sets how much reading a review does, and so what it costs and how long it takes.

At every depth, a finding is only posted if the verifier confirms it with a citation that holds: the quoted code must really be on the cited line. When a time budget runs out, the verified findings are posted and the review is marked partial, with the files it did not reach.

Where depth is set#

• Workspace defaults in Policies: the depth, profile and checks every PR gets unless something more specific applies.
• Policy rules in Policies: conditional depth by repo, branch, path or label (below).
• Per repo in Repositories: which base branches are reviewed, and a depth per branch.
• In the repo with .forseti.yaml, which takes precedence over the dashboard for that repo.
• One-off with @forseti review deep (or another depth) on a PR.

An owner can lock keys for the whole workspace, such as a maximum depth. Locks win over everything else. Comment @forseti config on a PR to see which layer set each value.

Policy rules#

A rule reads as a sentence: on PRs to main touching src/payments/**, run Deep. Each rule has conditions and what to apply.

• Every condition you set must hold. Conditions you leave empty match everything.
• Rules are checked top to bottom and the first match wins, so put specific rules above general ones.
• Up to 100 rules, with at most 50 globs in any one condition and 200 across all rules.

Before you save, the Policies page shows the monthly impact of a change, worked out by replaying the sizes of your last 30 days of PRs through the price estimate. No model is called for the preview.

Dimensions#

Dimensions add focused passes. Each switch in the dashboard shows what it adds to the price.

Glance runs no dimensions. Standard's single finder already covers correctness and obvious security issues; switching a dimension on adds a specialist. In Deep, switching one off saves its share.

Severity, strictness and the inline cap#

The PR's verdict follows its open findings: blocking if any blocking finding is open, needs changes if should-fix findings are open, otherwise clear.

The strictness profile picks which severities go inline: quiet (Blocking only), balanced (Blocking and Should fix, the default) or thorough (all three). The inline cap (7 by default, up to 50) limits comments per review, with a per-file limit so one file cannot use the whole cap. Everything else is listed in the sticky summary with the reason, so nothing is hidden.

How a review is priced#

Reviews are paid in credits, and one credit is £0.01. There is no fixed price per depth: the price follows the size of the change, the depth and the dimensions switched on. The calculator on the Pricing page uses the same formula as the product.

1. Before the review, Forseti estimates a typical and a high-end price and shows the estimate on the check run.
2. It reserves the high-end figure against your balance and caps.
3. When the review finishes, you are charged the actual model cost, converted to credits, and the rest of the reservation is released.

Every stage of a review records its model, tokens and cost, so the dashboard can show where each credit went. New workspaces start with 2,500 trial credits. Top-ups come in £20, £100 and £500 packs.

Price Guard: caps and what happens at a cap#

Caps are checked at the moment credits are reserved, before any model is called.

Owners, admins and the billing role set caps under Spend and choose what happens at a cap: drop to Glance (the default) or pause. If even a Glance review would not fit, the review pauses. Either way, Forseti says so on the PR with one neutral check run, never a stream of comments, and never skips silently.

A Deep review someone asks for above the per-PR cap is not degraded: Forseti replies with the price and waits for @forseti confirm. Confirming waives the per-PR cap for that one review; monthly caps still apply. Caps cannot be set in .forseti.yaml, so a repo file can never raise spend.

Workspaces can also set monthly ceilings for a developer, a team or a repo, with the same choice of dropping to Glance or pausing when one is reached.

A worked setup#

A common shape for a product team, as policy rules or as a file:

• Workspace default: Standard, balanced.
• Rule: PRs touching src/payments/** or src/auth/** run Deep with the security dimension.
• Rule: PRs labelled docs run Glance.
• Caps: £5 per PR, drop to Glance at the monthly cap.

depth:
  default: standard
  "release/*": deep
profile: balanced

Path and label conditions live in dashboard policy rules; the file handles depth by branch, paths to ignore and path instructions.