Quickstart

Start with the GitHub App. Hosted trials cover up to three organizations per installing identity; BYOK covers additional organizations. It reviews new non-draft pull requests after setup. Add the CLI and GitHub Action for local reviews and merge blocking.

1. GitHub App

Install the App and select all repositories or a chosen set. Your hosted 30-day trial starts automatically without a card. Postil reviews new non-draft pull requests in those repositories after setup. You can use your own provider from organization settings. Private reviews pause when the trial ends unless a paid plan is active.

Draft pull requests are skipped until marked ready. Existing open pull requests are not reviewed retroactively unless a review is requested again. You can disable individual repositories from the organization dashboard.

Install the GitHub App

The GitHub App also handles @postil mentions. Exact review commands on a pull request run the structured reviewer; questions get a compact thread reply. It reviews and answers only: it never opens PRs or pushes commits. GitHub only today.

2. 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 MODEL_API_KEY=sk-or-...
export POSTIL_API_KEY="$MODEL_API_KEY"

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

# No native Windows build yet — install.sh covers Linux and macOS only.
# Easiest path today: WSL, then follow the Linux tab above.

# Without WSL, build from source with a Rust toolchain:
cargo install --git https://github.com/postil-dev/postil-cli --locked
$env:MODEL_API_KEY = "sk-or-..."
$env:POSTIL_API_KEY = $env:MODEL_API_KEY

# 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.

3. GitHub Actions

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

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
      - uses: postil-dev/postil-action@00442e2340edaa4a681955dbb25e20650ca1514c # tested pair
        with:
          cli-ref: dcf4e34c4804d4bf64705ab6367c883cea23b33a
          cli-release: v0.7.2
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          MODEL_API_KEY: ${{ secrets.MODEL_API_KEY }}
          POSTIL_API_KEY: ${{ secrets.MODEL_API_KEY }}

The action SHA above is an example full commit SHA, and cli-ref pins the postil-cli release commit. Pick full SHAs you have verified from the postil-action repository and the postil-cli repository before updating. The action refuses anything but a full 40-character commit SHA for cli-ref: tags move, SHAs do not.

As a recommended bonus, make review failures block merges by requiring postil/gate in branch protection. See the gate.

Next steps

Optionally 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.