Quickstart

Three ways in, one engine. Pick the one that matches where you want the review to happen.

1. Local CLI

Install the binary and point it at an OpenAI-compatible endpoint. The default is OpenRouter.

curl -fsSL https://postil.dev/install.sh | sh
# or build from source:
# cargo install --git https://github.com/postil-dev/postil-cli --locked
export OPENROUTER_API_KEY=sk-or-...

# review what you are about to commit
postil review --staged

# review a branch against main
postil review --base main

On a clean diff the command prints nothing of substance and exits 0. Findings print with severity, path, line, confidence, and kind; gate-failing findings exit 1.

Verify your setup before the first real review with postil doctor: it checks the endpoint, key, and model and reports exactly what is wrong if anything is.

2. GitHub Actions

The composite action installs a CLI pinned to a full 40-character commit SHA and runs the same review in CI:

name: review
on:
  pull_request:
    types: [opened, synchronize, reopened, ready_for_review]

jobs:
  postil:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      pull-requests: write
      checks: write
    steps:
      - uses: actions/checkout@v4
      # the @v1 tag will exist after the first tagged release of the action
      - uses: postil-dev/postil-action@v1
        with:
          cli-ref: 6b9d2db621e12bd558f72ba3e7bd8ecc092cd93a
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          OPENROUTER_API_KEY: ${{ secrets.OPENROUTER_API_KEY }}

The cli-ref above is current as of June 2026; check the postil-cli repository for the latest. The action refuses anything but a full 40-character commit SHA — tags move, SHAs do not.

3. Hosted GitHub App

Install the App from the install page, select repositories, and open a pull request. Postil creates two check-runs — postil/review and postil/gate — and reviews the diff. Drafts are skipped until marked ready.

The hosted app also answers @postil mentions: reply to one of its review comments, mention it in a PR or issue comment, and it responds in thread. It reviews and answers only — it never opens PRs or pushes commits. GitHub only today.

To make the gate binding, require postil/gate in branch protection. See the gate.

Next steps

Tune thresholds and ignores in .postil.yaml — or keep your existing .coderabbit.yaml; Postil reads it.
Preview any config change with postil plan before deploying it.
Run the whole stack yourself: self-hosted guide.