Set up the forge
Cawdit posts its reviews as an ordinary Forgejo or Arbinel account.
This guide creates that account, its token, and, for cawdit serve, the webhooks and the OAuth2 applications.
Create a bot account
Create a separate account for Cawdit, such as cawdit-bot, rather than using your own.
Its login appears on every review, and people mention it to talk to Cawdit.
A separate account also keeps Cawdit’s token apart from yours, so you can revoke it alone.
On an instance you administer, create the account under Site administration > User accounts. On a public instance such as codefloe.com, register it like any other account.
Make the account recognisable
Forgejo has no apps like GitHub’s, so the account itself is what people see next to every review. Sign in as the account and open Settings > Profile:
- Set Full name to
Cawdit, which Forgejo shows on the profile, and next to comments when the instance setsDEFAULT_SHOW_FULL_NAME = trueunder[ui]. - Under Avatar, upload the Cawdit avatar.
- Set Biography to a line such as
Automated code review by Cawdit, and Website to the dashboard’spublic_url.
On an instance you administer, also mark the account as a bot, so Forgejo shows a bot label after its name on every comment. Forgejo has no setting for it, so change the account’s type in the database and restart Forgejo:
Type 4 is Forgejo’s bot type, and the account keeps its token, its permissions and its sign-in.
Give it access to the repositories
Cawdit needs write access to each repository it reviews, because Forgejo lets only such accounts set commit statuses. Add the account as a collaborator with Write permission, or add it to a team of the organisation with write access to the repositories.
cawdit serve answers @cawdit commands only from accounts with write access, and asks Forgejo who has it.
Forgejo tells only accounts with admin access to the repository.
With write access alone, Cawdit falls back to the accounts a pull request can be assigned to.
In a repository of a person, those are exactly the accounts with write access.
In a repository of an organisation, they also include members of teams that can only read pull requests, and Forgejo does not tell Cawdit who belongs to which team.
So with write access alone, an organisation’s repository works as follows:
@cawdit reviewand questions work for every account a pull request can be assigned to, which costs only tokens.@cawdit ignoredismisses a finding only when every team with access to the repository has write access or more. Otherwise Cawdit replies that it cannot confirm the access, and logs the warningnot dismissing a finding: the forge does not tell whether the account has write access.
Give the bot account Admin permission on the repository to make every command’s check exact.
Then Forgejo tells Cawdit each account’s permission, and @cawdit ignore works for everyone with write access.
Admin permission also lets Cawdit add its webhook to the repository on its own, unless an owner connects the organisation.
Create the token
Sign in as the bot account and open Settings > Applications > Access tokens. Create a token with these scopes:
| Scope | Why Cawdit needs it |
|---|---|
write:repository |
Read pull requests, their diffs and files, and .cawdit.toml, then post reviews and set commit statuses. |
write:issue |
Edit its own comments, such as to mark a finding fixed. |
read:user |
Read its own account, so it can tell its earlier comments from those of other people. |
cawdit serve and cawdit review check the token’s scopes when they start.
A missing scope stops them with an error such as the token lacks the scopes read:user: create a token with the scopes write:repository, write:issue, read:user.
They log a warning when the token has scopes Cawdit does not need, such as all, and when the bot account is an admin of the whole instance.
When the forge cannot be reached at start, they log a warning and start anyway.
Store the token as a secret right away, because Forgejo shows it only once.
For the Crow plugin, that is a repository secret, as the quick start shows.
For cawdit serve, it is a file or an environment variable that forges.<name>.token references.
Connect repositories and organisations
Only cawdit serve needs a webhook.
The Crow plugin runs inside the pipeline and needs none.
Admins connect organisations or repositories in the dashboard’s settings, and Cawdit then keeps the webhooks in sync on its own.
The settings need the dashboard’s sign-in, see Let people sign in to the dashboard, and public_url in the deployment configuration.
Without them, set up a webhook by hand.
Let Cawdit keep the webhooks in sync
cawdit serve syncs the webhooks of each forge every forges.<name>.sync_interval, ten minutes by default.
An admin can also select Sync now under Settings.
For each owner in forges.<name>.allowed_owners, the sync does one of two things:
- When an owner connected the organisation, as the next section describes, Cawdit keeps one organisation webhook for all its repositories. It removes its own repository webhooks in the organisation, so no event arrives twice.
- Otherwise it adds a repository webhook to each repository of the owner where the bot account has Admin permission. Forgejo lets only admins of a repository see and change its webhooks.
So a repository connects on its own once the bot account is an admin of it, or once an owner connected its organisation.
Each webhook has the target URL <public_url>/webhooks/<name>, the content type application/json, and the events that setting up a webhook by hand lists.
Cawdit signs it with the owner’s secret from owner_webhook_secrets, or else with webhook_secret.
The sync repairs a webhook that somebody turned off, whose events changed, or whose secret changed in the configuration, and removes duplicates.
It touches only the webhooks that send to Cawdit’s URL, and leaves every other webhook alone.
With allowed_owners = ["*"], the sync adds webhooks only to the repositories Cawdit already knows, because it reviewed them or an admin connected them, and to the organisations an owner connected.
That keeps it from adding a webhook to every repository the bot account can see on a public forge.
Only one sync of a forge runs at a time, however many replicas of cawdit serve run.
Settings shows when the last sync ran, what it changed, and why it failed for a repository or an organisation, and the metrics count the syncs and their errors.
Connect a repository by hand
Settings lists every repository the bot account can access, each under the organisation that owns it, and the rest under Other repositories. To connect one before the next sync, find it, select Connect, and confirm. Connecting a repository again updates its webhook instead of adding a second one.
Disconnect removes the webhook, turns the repository’s reviews off, and records who disconnected it. The sync never connects a disconnected repository again, until an admin selects Connect. A repository that an organisation’s webhook covers keeps receiving its events, which Cawdit ignores while the repository’s reviews are off.
The switch next to each repository turns its reviews on or off without touching the webhook. While reviews are off, Cawdit ignores the repository’s webhooks and skips the reviews already queued.
Each row shows the repository’s status, and says what to do when something blocks it:
| Status | Meaning |
|---|---|
| Connected | Cawdit’s webhook is on the repository. |
| Connected (organisation webhook) | The webhook of the repository’s organisation delivers its events. |
| Disconnected | An admin disconnected the repository, and the sync leaves it alone. |
| Not connected | The repository has no webhook to Cawdit, and an admin or the next sync can connect it. |
| Bot lacks admin | The bot account has only read or write access, so Cawdit can neither see nor add the webhook. |
| Webhook unknown | The forge failed to list the repository’s webhooks. |
| Owner not allowed | The owner is not in allowed_owners, so Cawdit would ignore the webhook. |
Everybody who signs in sees the list, limited to the repositories they may read, but only admins can change it.
Connect an organisation
Forgejo has no installations of apps: an OAuth2 application always acts as the person who authorised it. So an owner of the organisation authorises Cawdit once, and Cawdit keeps that token only to manage the organisation’s webhook. Reviews are still posted by the bot account, which needs write access to the repositories as before.
Create the OAuth2 application once per forge:
- Sign in to the forge as the account the application should belong to, such as the bot account, and open Settings > Applications.
- Under Manage OAuth2 applications, create an application named
Cawdit, with the redirect URI<public_url>/api/v1/settings/organizations/callback, such ashttps://cawdit.example.com/api/v1/settings/organizations/callback. - Keep Confidential client selected, and save.
- Give the client ID to Cawdit as
forges.<name>.app_client_idand the client secret asforges.<name>.app_client_secret. - Create a key with
openssl rand -hex 32, and give it to Cawdit asdashboard.secrets_key, which encrypts the stored tokens.
When people sign in through the forge, the application of oauth_client_id can serve here too.
Add the second redirect URI to it, one per line, and set app_client_id and app_client_secret to the same values.
When people sign in through SSO only, as on codefloe.com, create the application above.
Then connect an organisation:
- Open Settings, which shows a card for each owner in
allowed_owners. Withallowed_owners = ["*"], select Connect organisation and type the organisation’s name instead. - Select Connect on the organisation’s card. This needs a Cawdit admin who is signed in to the forge, in the same browser, as an owner of the organisation.
- The forge asks the owner to authorise Cawdit with the scopes
read:userandwrite:organization. - Cawdit checks that the person is an owner of the organisation, stores the token encrypted, and starts a sync, which adds the organisation webhook.
Forgejo limits the token to the scopes it was granted, and it remembers the first authorisation of an application without asking again. If an owner authorised the application before with other scopes, revoke it under Settings > Applications > Authorized OAuth2 applications on the forge first.
Cawdit refreshes the token when it expires. The organisation shows as Needs reconnection when the forge refuses the token, because the owner revoked it or did not use it for a long time. It does too when the person who authorised Cawdit is no longer an owner of the organisation. The sync then adds repository webhooks again, until an owner connects the organisation again.
Disconnect removes Cawdit’s organisation webhook and deletes the stored token, and the sync falls back to repository webhooks. When the token no longer works, Cawdit cannot remove the webhook, and says so: remove it under the organisation’s Settings > Webhooks on the forge.
A user’s account has no organisation webhook, so the repositories of a user always get repository webhooks.
Set up a webhook by hand
People who connect their own repositories without an admin find these settings on the dashboard’s Setup page, under Set up a webhook by hand. It shows the target URL, the events, the bot account and the allowed owners of the running server, but never a secret. A person who signs in before any repository was reviewed sees the same steps on the repositories page.
- Create a random secret, such as with
openssl rand -hex 32, and give it to Cawdit asforges.<name>.webhook_secret. - In the repository, open Settings > Webhooks > Add webhook > Forgejo. For every repository of an organisation, add it in the organisation’s settings instead.
- Set the Target URL to
<public_url>/webhooks/<name>, where<name>is the forge’s name in the deployment configuration, such ashttps://cawdit.example.com/webhooks/codefloe. - Set the HTTP method to
POSTand the POST content type toapplication/json. - Set the Secret to the same secret.
- Under Trigger on, select Custom events and then these four under Pull request events:
- Modification, for opened, reopened and edited pull requests.
- Synchronized, for new commits on the pull request.
- Comments, for comments that mention Cawdit.
- Reviews, for replies that mention Cawdit in an inline thread.
- Save the webhook, and select Test delivery.
A test delivery answers 200 with a reason, because it is a push event that Cawdit ignores. A 401 means the secrets differ, and a 404 means the forge name in the URL is wrong. The HTTP server reference lists every status.
Use a secret per owner
Every repository or organisation that installs the webhook knows its secret.
With one secret for the whole forge, the admin of one owner’s repository could sign webhooks for the repositories of another owner, which queues reviews and spends tokens.
When several people or teams install the webhook, give each owner its own secret in forges.<name>.owner_webhook_secrets, and set require_owner_secrets = true so no shared secret is left.
The deployment configuration has an example.
A Forgejo instance refuses to send webhooks to private addresses unless its webhook.ALLOWED_HOST_LIST setting allows them.
When Cawdit runs next to Forgejo on a private network, add the address there.
Allow the owners
cawdit serve reviews only the repositories of the owners in forges.<name>.allowed_owners.
List your users and organisations, or set ["*"] to allow every owner on the instance.
The list stops strangers on a public instance from spending your model budget by adding the webhook to their own repositories.
Arbinel
Arbinel is a Forgejo fork, and Cawdit sets it up the same way.
Cawdit reads the instance’s API description, /swagger.v1.json, about once an hour to find two optional features:
- Resolving a review thread, which Cawdit does when a finding is fixed.
- Replying in a review thread.
Plain Forgejo has neither, so Cawdit edits its comment to say a finding is fixed instead of resolving the thread. It answers a question in a thread with a separate review that quotes the question. On Arbinel it resolves the thread and replies inside it.
Let people sign in to the dashboard
cawdit serve has a dashboard, and people sign in to it with their forge account.
Skip this section if you do not need the dashboard.
- Sign in as the account that the application should belong to, such as the bot account, and open Settings > Applications.
- Under Manage OAuth2 applications, create an application named
Cawdit, with the redirect URI<public_url>/api/v1/auth/callback, such ashttps://cawdit.example.com/api/v1/auth/callback. - Keep Confidential client selected, and save.
- Give the client ID to Cawdit as
forges.<name>.oauth_client_idand the client secret asforges.<name>.oauth_client_secret. - Create a session key with
openssl rand -hex 32, and give it to Cawdit asdashboard.session_key.
Cawdit asks for the scopes read:user and read:repository, and shows each person only the repositories the forge lets them read.
The logins in forges.<name>.admins see every repository.
To let people sign in with a company account instead, see Set up SSO sign-in.