.forseti.yaml reference

A .forseti.yaml file at the root of a repository sets that repo's review settings in code, so they are versioned and reviewed like everything else. It is optional: without it, the dashboard settings apply.

# Review every PR to main at Deep, everything else at Standard.
depth:
  default: standard
  main: deep

Where the file is read from#

Forseti reads .forseti.yaml from the pull request's base commit, never from the PR itself. A pull request cannot change how it is reviewed: a change to the file takes effect for PRs opened after it merges.

• Keys may sit under a top-level reviews: block or at the top level. Both forms below are the same.
• Files over 20,000 bytes are ignored.
• Unknown keys are ignored, so a typo never breaks reviews. Check the result with @forseti config.
• While the file exists, the repo shows Managed by .forseti.yaml in the dashboard.

reviews:
  profile: quiet

# is the same as

profile: quiet

Keys#

Every key is optional. A key you leave out falls through to the dashboard, then to the product default.

depth#

One of glance, standard, deep or molecular. To vary depth by target branch, use a map: default plus base-branch globs. The first matching glob, in the order written, wins.

depth:
  default: standard
  main: deep
  "release/*": deep
  "docs/*": glance

molecular is in early access. Choosing it runs a Deep review and says so on the PR. An owner can set a maximum depth for the workspace; a file asking for more runs at that maximum, and @forseti config shows why. Depths are explained in Policies & depth.

profile and max_inline_comments#

The profile decides which severities are posted as inline comments. Everything else goes to the summary, with the reason.

max_inline_comments caps inline comments per review. Findings over the cap are listed in the summary, so nothing is lost. Forseti also spreads comments across files rather than spending the whole cap on one.

branches#

Without branches, only pull requests into the default branch are reviewed. include lists the base branches to review; exclude is checked first and always wins.

• Plain names must match exactly. Any of * ? [ ] { } makes the list glob patterns.
• Globs are anchored to the whole name: develop never matches develop-2. Use develop* for that.

branches:
  include: ["main", "release/*", "hotfix/**"]
  exclude: ["release/legacy-*"]

paths#

paths.ignore takes globs of files Forseti should not review. Lockfiles, generated, vendored, minified, snapshot and binary files are already skipped, and secret files such as .env are never sent to a model, so you do not need to list those.

paths.instructions gives reviewers context for parts of the codebase: up to 20 entries, each a path glob and a plain-English text.

paths:
  ignore: ["**/*.snap", "fixtures/**"]
  instructions:
    - path: "src/billing/**"
      text: "Amounts are integer pence. VAT is applied once per band."

dimensions#

Dimensions switch focused review passes on or off. Names: security, performance, tests, architecture, data_migrations, contracts, style, docs and accessibility. Other names are ignored.

Only list the ones you want to change: each depth has its own defaults, and every extra pass adds to the price. What each depth runs is in Policies & depth.

packs#

Turns on domain packs for this repo: money, migrations, tenancy-auth, pii and architecture, plus any custom packs your workspace defines. Up to 20. See Domain packs.

packs: ["money", "tenancy-auth"]

skip and drafts#

skip.labels replaces the default list (no-review, skip-review): a PR carrying any of them is not reviewed automatically. skip.authors lists logins to leave alone. skip.bots: false reviews PRs from bot accounts, which are skipped by default. drafts: true reviews drafts as well.

A review someone asks for with @forseti review still runs on a skipped PR. Some rules are not settable from the file: PRs that change only lockfiles, generated or vendored files are always skipped; forks from non-members follow the workspace setting; and the title markers [skip review] and [forseti skip] are fixed.

Team rules: .forseti/rules.md#

Next to .forseti.yaml, a .forseti/rules.md file on the base branch holds your team's review rules in plain English. Every review reads it, alongside AGENTS.md, CLAUDE.md and REVIEW.md if you have them.

## Payments
- Amounts are integer pence; never use floats.
- Every refund path must be idempotent.

## API
- Public endpoints check the caller's plan before doing work.

Write it by hand, or export it from your workspace's team memory so the lessons Forseti has learned live in the repo too. Guidance files are read up to 12,000 characters each and 24,000 in total, with secrets redacted.

What the file cannot set#

Spend caps. A repo file must never be able to raise spend, so caps is ignored with a warning. Caps live in the dashboard under Spend.

Workspace locks. Settings are resolved per key in this order, and each key records where it came from:

1. workspace locks set by an owner (for example a maximum depth);
2. .forseti.yaml on the base commit;
3. the repo's dashboard settings;
4. the first matching workspace policy rule;
5. workspace defaults;
6. product defaults.

Mistakes and how to check#

A file that is not valid YAML contributes nothing, and reviews carry on with the other layers. A bad value (say depth: fast) is ignored with a warning. Comment @forseti config on any PR to see the resolved settings, the source of each key and any warnings.

# .forseti.yaml (on the base branch)
reviews:
  depth:
    default: standard
    "release/*": deep
  profile: balanced
  max_inline_comments: 5
  drafts: false
  branches:
    include: ["main", "release/*"]
    exclude: ["release/legacy-*"]
  paths:
    ignore: ["**/*.snap", "docs/generated/**"]
    instructions:
      - path: "src/payments/**"
        text: "Money is integer pence. Never use floats for amounts."
      - path: "db/migrations/**"
        text: "Every migration must be reversible."
  dimensions:
    security: true
    tests: true
    style: false
  packs: ["money", "migrations"]
  skip:
    labels: ["wip", "no-review"]
    authors: ["release-bot"]
    bots: true