Pre-merge checks

Pre-merge checks are rules about a pull request written in plain language. Anvil judges each one against the whole PR on every review and reports the result. Use them for things a linter can't check: "the description says why", "every migration is reversible", "new endpoints have tests".

Define checks #

Add them under checks in .anvil.yaml:

checks:
  - name: Description explains why
    instructions: "The PR description says why the change is needed, not only what changed."
    mode: warning
  - name: Migrations are reversible
    instructions: "Every new file in migrations/ has a down migration that undoes it."
    mode: error
  - name: New endpoints have tests
    instructions: "Every new route under server/api/ has at least one test that calls it."
    mode: warning

Each check has:

• name: a short label, shown in the walkthrough and in the commit status.
• instructions: what must be true for the check to pass. Be specific; Anvil reads the code to decide, so name directories and conventions.
• mode: warning (the default), error or off.

Results #

Each check comes back as pass, fail or inconclusive, with a one-line explanation. Results appear in a table in the walkthrough comment and on the Anvil Verify page of the pull request workspace, next to the CI jobs for the same commit.

An inconclusive result never fails the status.

Block merges #

To stop a PR from merging while an error check fails:

1. Give the Anvil user Write access to the repository, so it can set commit statuses.
2. In the repository's Settings → Branches, edit the protection rule for your main branch, enable Status check and add Anvil as a required check.

The status is set again on every review, so fixing the problem and pushing turns it green.

Coming #

• Built-in checks for the title, description, docstring coverage and linked issues.
• One commit status per check (Anvil/<check>), so each can be required on its own.
• @anvil run pre-merge checks and @anvil ignore pre-merge checks.