Skip to content
Cawdit

Quick start

You add Cawdit to one repository as a step of your Crow pipeline. At the end, Cawdit reviews a pull request, posts its findings as inline comments, and sets a commit status.

The Crow plugin needs no server and no database. It runs cawdit review once per pipeline and reads what it posted before from its own comments.

What you need

  • A repository on Forgejo or Arbinel, with Crow CI enabled for it.
  • Admin access to the repository, to add a collaborator and secrets.
  • An API key for Anthropic, or another model provider from Configure a model provider.

Create the bot account

  1. Create a Forgejo account for Cawdit, such as cawdit-bot.
  2. In your repository, open Settings > Collaborators and add cawdit-bot with Write permission.
  3. Sign in as cawdit-bot, open Settings > Applications > Access tokens, and create a token with the scopes write:repository, write:issue and read:user.
  4. Copy the token, because Forgejo shows it only once.

Set up the forge explains each scope.

Add the secrets to Crow

In Crow, open the repository’s settings and select Secrets. Add two secrets:

Name Value Events Images
cawdit_forge_token The bot’s token. pull_request docker.io/cawdit/cawdit:plugin-main
anthropic_api_key Your Anthropic API key. pull_request docker.io/cawdit/cawdit:plugin-main

The event and image filters hand the secrets only to the Cawdit plugin step of a pull request pipeline. Create both secrets before you add the pipeline, because Crow rejects every pipeline of a repository that names a missing secret.

Add the pipeline

Create .crow/cawdit.yaml on a new branch:

when:
  - event: pull_request

# The plugin reads the pull request through the forge's API.
skip_clone: true

steps:
  review:
    image: docker.io/cawdit/cawdit:plugin-main
    pull: true
    settings:
      model: claude-opus-5-5
      verify_model: claude-sonnet-5-5
      api_key:
        from_secret: anthropic_api_key
      forge_token:
        from_secret: cawdit_forge_token
      dry_run: true

dry_run: true makes the first run safe: Cawdit calls the model but posts nothing, and prints the review in the step’s log instead.

Open a pull request

  1. Add a small change with a bug next to the pipeline file, such as a function that divides by a number without checking it for zero.
  2. Push the branch and open a pull request.
  3. In Crow, open the pipeline of the pull request and then the review step.

The log ends with the review that Cawdit would post:

# Dry run of the review of alice/demo#1 at 3ee1ccdc4218

## Review (COMMENT)

### Cawdit review

Cawdit found 1 new finding.
...

### `calc.py` line 2

**Error** (bug): Division by zero when b is 0
...

## Commit status

- `cawdit` on 3ee1ccdc4218: failure, 1 open finding of severity error

Your finding depends on your change and the model. When the log shows an error instead, the most common causes are a token without read:user and a missing secret.

Post the review

Remove the dry_run: true line, and add fail_on: error in its place:

      fail_on: error

Push the change to the same branch. The pipeline runs again, and this time Cawdit:

  • posts a review with one inline comment per finding, written by cawdit-bot,
  • sets the commit status cawdit to failure while an open finding of severity error remains,
  • fails the review step for the same reason, because of fail_on.

Now fix the bug and push again. Cawdit reviews only what changed since its last review, edits its old comment to say the finding is fixed, and sets the status to success.

Tune the review

The repository decides how strict the review is, with a .cawdit.toml at its root:

[review]
min_severity = "warning"
max_findings = 10

[paths]
ignore = ["vendor/**"]

Cawdit reads this file from the base branch, so it takes effect once you merge it. The repository configuration reference lists every key.

Next steps

  • Merge .crow/cawdit.yaml, so every pull request gets a review.
  • Read the security model before you enable the plugin on a repository that takes pull requests from forks.
  • Run Cawdit as a server for many repositories, with Docker or Helm.