Postil

GitLab

Postil speaks GitLab through the same review engine it uses for GitHub. It posts inline discussion notes on the merge request and reports the gate verdict through its exit code, which a CI job fails on. The hosted app does not reach GitLab; you run the CLI in your own CI with your own inference key.

1. Create a project access token

In your project, create a project (or group) access token with the api scope and at least Developer role so it can read the MR diff and post discussion notes. Store it as a masked CI/CD variable named GITLAB_TOKEN. Add your inference key (MODEL_API_KEY) the same way.

2. Add the CI job

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_IID

The job runs only on merge-request pipelines. A gate-failing review exits 1 and fails the job; a clean review exits 0 and posts nothing; see exit codes. To make the gate binding, mark the job required to merge in the project's merge-request settings (or require a green pipeline).

3. Self-managed instances

For GitLab Self-Managed, point the CLI at your instance with the GITLAB_API_URL environment variable:

export GITLAB_TOKEN=glpat-...
export MODEL_API_KEY=...
export POSTIL_API_KEY="$MODEL_API_KEY"
export GITLAB_API_URL=https://gitlab.example.com/api/v4
postil review --forge gitlab \
  --repo $CI_PROJECT_PATH --pr $CI_MERGE_REQUEST_IID

The token, scopes, and gate semantics are identical to GitLab.com. No outbound connection is made to Postil; the review runs entirely inside your CI with your inference key.

Local review against a GitLab MR

You do not need CI to try it. With GITLAB_TOKEN set locally:

export GITLAB_TOKEN=glpat-...
export MODEL_API_KEY=...
export POSTIL_API_KEY="$MODEL_API_KEY"
postil review --forge gitlab --repo group/project --pr 88
# self-managed:
export GITLAB_API_URL=https://gitlab.example.com/api/v4
postil review --forge gitlab --repo group/project --pr 88

The @postil bot

GitLab covers both issues and merge requests for postil respond: mention @postil on either and reply with the CLI:

postil respond --forge gitlab --repo group/project --pr 88 \
  --comment "@postil is this safe?"
postil respond --forge gitlab --repo group/project --issue 12 \
  --comment "@postil what's the likely cause?"

Parity and limits

  • Same gate thresholds, envelope schema, and exit codes as GitHub; see the CLI reference and exit codes.
  • Inline notes are posted on the MR diff; the gate is enforced via the CI job result rather than a named external check-run.
  • The hosted Postil app is GitHub-only today; on GitLab you run the CLI in CI, including for the interactive bot.
  • See the forges overview for Bitbucket and Azure DevOps, both supported through the same forge abstraction.