Getting started

A review is one command that reads a diff and exits. There is no server to run, no database to provision and no webhook to register — so installing it means adding a job to CI you already have.

What you need#

  • Python 3.10 or newer, if you are running the CLI directly. The GitHub Action and the container image bring their own.
  • A full clone. The review diffs against the base branch, which a shallow clone does not contain. Every integration page says how to turn shallow clones off.
  • An API key for one provider — Anthropic, OpenAI, Azure, Bedrock — or a local Ollama model, which needs no key and costs nothing.
  • ripgrep is optional. It makes the caller search much faster; without it a pure-Python walk does the same work with the same results.

Try it first without a key#

Before wiring anything into CI, see what the pipeline assembles. --dry-run stops before the first model call, so it needs no key and costs nothing:

pip install "git+https://github.com/groundtruth-code-review/groundtruth-code-review.git"

groundtruth review \
  --repo /path/to/your/repo \
  --base main \
  --head HEAD \
  --dry-run --format text

You get the cost estimate for the review pass and the list of context that would have been sent. If that looks wrong — wrong files, missing callers — fix it here, before spending anything.

Add it to GitHub#

One workflow file and one repository secret:

# .github/workflows/groundtruth.yml
on: pull_request
concurrency:
  group: groundtruth-${{ github.event.pull_request.number }}
  cancel-in-progress: true
permissions:
  pull-requests: write
jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7
        with: { fetch-depth: 0 }
      - uses: groundtruth-code-review/groundtruth-code-review/adapters/github@main
        with: { model: anthropic/claude-sonnet-5 }
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}

Add ANTHROPIC_API_KEY under Settings → Secrets and variables → Actions, and that is the whole install. GitLab, Bitbucket Cloud and Kubernetes take about the same.

Three settings people miss. fetch-depth: 0 gives the job the history it needs to diff against the base ref. pull-requests: write lets it post; without it the review runs and then fails at the last step. concurrency cancels the review for a pull request's previous push instead of letting two runs race to write the same summary comment — see what happens if I push twice quickly.

What happens on the pull request#

Two things, and only ever these two:

  • One summary comment, created on the first run and edited in place on every push after. It never stacks up.
  • One inline comment per finding, on the line the finding quotes, carrying the severity, the category, the confidence and the quoted line.

If nothing clears the quality gate, you get the summary comment saying so and no inline comments at all. That is the normal, intended outcome on a clean diff.

Next#

Configuration →