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
- Create a Forgejo account for Cawdit, such as
cawdit-bot. - In your repository, open Settings > Collaborators and add
cawdit-botwith Write permission. - Sign in as
cawdit-bot, open Settings > Applications > Access tokens, and create a token with the scopeswrite:repository,write:issueandread:user. - 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:
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
- 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.
- Push the branch and open a pull request.
- In Crow, open the pipeline of the pull request and then the
reviewstep.
The log ends with the review that Cawdit would post:
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:
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
cawditto failure while an open finding of severityerrorremains, - fails the
reviewstep for the same reason, because offail_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:
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.