Anvil beta
DocsBlock merges with pre-merge checks
Overview
Get started
IntroductionQuickstart: code reviewQuickstart: CI runnersConnect your agent
Guides
Add repositoriesMove workflows to Anvil runnersHost a repository on AnvilUse the pull request workspaceBlock merges with pre-merge checksTeach Anvil your rulesLet Anvil change codeFind failing, slow and flaky CIWatch CPU and memoryInvite your teamRun Anvil on your own server
Reference
ConfigurationCommandsHow reviews workRunner sizes and labelsMCP serverEnvironment variables
More
Security and dataFAQ
Docs/Guides

Block merges with 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:

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.

Mode When the check fails
warning Marked ⚠️ in the walkthrough. The commit status stays green
error Marked ❌ in the walkthrough, and the Anvil commit status is set to failure: "Failed: Migrations are reversible"
off The check isn't run

An inconclusive result never fails the status.

Block merges #

Make the Anvil status required, so a pull request can't merge while an error check fails.

  1. In the repository on GitHub, open Settings → Branches (or Rules) and edit the rule for your main branch.
  2. Turn on Require status checks to pass.
  3. Search for Anvil and add it. It's listed once Anvil has set it on a commit.
  1. Open the repository's Settings → Branch protection and add or edit the rule for your main branch.
  2. Turn on Require status checks and add Anvil.

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.