Install
Choose your forge. Start reviewing pull requests.
On GitHub, one identity can start 30-day hosted trials for up to three organizations without a card. Additional organizations use BYOK. GitLab, Bitbucket, and Azure DevOps run the Postil CLI inside their own CI.
01
GitHub App
Thirty days free. No card required.
Choose all repositories or a selected set during installation. The 30-day hosted trial starts automatically for up to three organizations installed by one GitHub identity. Additional organizations start with BYOK access; connect a provider in organization settings. New non-draft pull requests are reviewed after setup. Draft pull requests are skipped until they are marked ready. Existing open pull requests are not reviewed retroactively unless a review is requested again.
Private reviews pause when the trial ends unless a paid plan is active. Public repositories remain free when you use your provider.
You can disable individual repositories from the organization dashboard. The App also answers @postil mentions on PRs and issues. It reviews and answers only; it never opens PRs or pushes commits.
The App uses the same review engine as the CLI, GitHub Action, and self-hosted stack.
Permissions requested: contents (read), pull requests (write), checks (write), metadata (read). Never write access to your code. See the security page.
02
GitHub Action
Optional CI reviews and merge blocking with your own model key.
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
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 requires a full 40-character commit SHA for cli-ref. Require postil/gate in branch protection when review failures should block merges. The GitHub App starts reviewing during the hosted trial without this CI workflow.
01
Install the CLI
Run Postil inside your forge's CI environment.
$ curl -fsSL https://postil.dev/install.sh | sh
Store a project or group access token as GITLAB_TOKEN and your inference key as MODEL_API_KEY.
The install script verifies the published SHA-256 checksum. Full checksum and cosign verification details remain below these forge instructions.
02
Add the CI job
Review merge requests on GitLab.com or GitLab Self-Managed.
The CLI posts inline discussion notes on the merge request and reports the gate verdict through the job's exit code.
postil:
image: debian:bookworm-slim
rules:
- if: $CI_PIPELINE_SOURCE == "merge_request_event"
before_script:
- apt-get update && apt-get install -y curl ca-certificates
- curl -fsSL https://postil.dev/install.sh | sh
- export PATH="$HOME/.local/bin:$PATH"
script:
- export POSTIL_API_KEY="$MODEL_API_KEY"
- postil review --forge gitlab
--repo $CI_PROJECT_PATH
--pr $CI_MERGE_REQUEST_IIDThe full guide covers token roles, required pipelines, local runs, and custom API URLs for self-managed instances. Follow the GitLab walkthrough.
01
Install the CLI
Run Postil inside your forge's CI environment.
$ curl -fsSL https://postil.dev/install.sh | sh
Store an access token as BITBUCKET_TOKEN and your inference key as MODEL_API_KEY. App passwords also require BITBUCKET_USER.
The install script verifies the published SHA-256 checksum. Full checksum and cosign verification details remain below these forge instructions.
02
Add the pipeline step
Review pull requests in Bitbucket Pipelines.
The CLI posts inline comments and makes a gate-failing review fail the pipeline step.
pipelines:
pull-requests:
'**':
- step:
name: postil review
image: debian:bookworm-slim
script:
- apt-get update && apt-get install -y curl ca-certificates
- curl -fsSL https://postil.dev/install.sh | sh
- export PATH="$HOME/.local/bin:$PATH"
- export POSTIL_API_KEY="$MODEL_API_KEY"
- postil review --forge bitbucket
--repo $BITBUCKET_WORKSPACE/$BITBUCKET_REPO_SLUG
--pr $BITBUCKET_PR_IDThe full guide covers access-token options, required branch restrictions, local runs, and Bitbucket Data Center. Follow the Bitbucket walkthrough.
01
Install the CLI
Run Postil inside your forge's CI environment.
$ curl -fsSL https://postil.dev/install.sh | sh
Store a Code (Read & Write) PAT as AZURE_DEVOPS_TOKEN and your inference key as MODEL_API_KEY.
The install script verifies the published SHA-256 checksum. Full checksum and cosign verification details remain below these forge instructions.
02
Add the pipeline step
Review pull requests in Azure Pipelines.
The CLI posts PR thread comments and makes a gate-failing review fail the pipeline step.
trigger: none
pr:
branches:
include: ['*']
pool:
vmImage: ubuntu-latest
steps:
- script: |
curl -fsSL https://postil.dev/install.sh | sh
export PATH="$HOME/.local/bin:$PATH"
org="$(basename "${SYSTEM_COLLECTIONURI%/}")"
postil review --forge azure \
--repo "$org/$SYSTEM_TEAMPROJECT/$BUILD_REPOSITORY_NAME" \
--pr "$SYSTEM_PULLREQUEST_PULLREQUESTID"
env:
AZURE_DEVOPS_TOKEN: $(AZURE_DEVOPS_TOKEN)
MODEL_API_KEY: $(MODEL_API_KEY)
POSTIL_API_KEY: $(MODEL_API_KEY)The full guide covers PAT permissions, required branch policies, local runs, and Azure DevOps Server. Follow the Azure DevOps walkthrough.
CLI
Installation and verification
Shared by local workflows and every self-run forge integration. Apache-2.0.
# install script (verifies the published SHA-256 over HTTPS)
$ curl -fsSL https://postil.dev/install.sh | sh
The script detects your OS and architecture, downloads the matching prebuilt binary from the GitHub release, verifies it against the SHA-256 checksum published alongside the release, and installs it to ~/.local/bin (no sudo required). Inspect it first if you prefer: curl -fsSL https://postil.dev/install.sh | less.
Release artifacts are signed with Sigstore keyless signing (cosign) via GitHub OIDC in release CI, alongside SHA-256 checksums. If cosign is installed, the script additionally verifies the keyless signature against the release workflow's certificate identity. There is no long-lived published key to manage. Without cosign it falls back to checksum verification only. Cross-check the published SHA-256 on the releases page if you want a second source.
# Rust toolchain, build from the repository
$ cargo install --git https://github.com/postil-dev/postil-cli --locked
Prebuilt targets: Linux x86_64 and aarch64, macOS arm64 and x86_64.
$ export MODEL_API_KEY=sk-or-...
$ export POSTIL_API_KEY="$MODEL_API_KEY"
$ postil doctor
Always run postil doctor before your first review. It checks the resolved config, the git work tree, your API key, a live probe of the model endpoint, and any forge tokens. A captured successful run reports:
$ postil doctor
[ok ] config loaded from defaults (model: local-doctor-probe, gate failOn: error, minConfidence: 0.6)
[ok ] git inside a git work tree
[ok ] api key POSTIL_API_KEY, OPENROUTER_API_KEY, MODEL_API_KEY, LLM_API_KEY is set (value not shown)
[ok ] model endpoint http://127.0.0.1:3117/v1 answered for model local-doctor-probe
[ok ] forge tokens presence only: GITHUB_TOKEN unset, GITLAB_TOKEN unset (only needed for remote review)
postil doctor: ready.This transcript was captured from the CLI against a loopback OpenAI-compatible endpoint. Your provider URL and model name will differ; key values are not printed.
Then review your staged changes with postil review --staged. See the quickstart and the full command reference.