Deployment configuration
The deployment configuration tells Cawdit which forges to review on, which model to call, and where its database is.
cawdit serve, cawdit migrate, cawdit review and cawdit eval all read it.
The configuration is one TOML file plus environment variables.
Pass the file with --config or the CAWDIT_CONFIG variable.
Every key can also come from an environment variable, and a variable overrides the file.
cawdit review usually runs without a file and reads only variables.
Run cawdit serve --print-config to see the configuration Cawdit loaded, with every secret shown as its reference.
Cawdit rejects a key it does not know, and it reports every problem at once with the key that has it.
Example
Secrets
A secret is never written into the configuration as a value. The configuration holds a reference to it instead, in one of two forms:
env:NAMEreads the environment variableNAME.file:/absolute/pathreads the file at that path, without one trailing line break.
A plain value is an error, and the error never repeats the value.
A secret file may be at most 64 KiB.
These keys are secrets: database.url, dashboard.session_key, dashboard.secrets_key, dashboard.oidc.client_secret, forges.<name>.token, forges.<name>.webhook_secret, forges.<name>.owner_webhook_secrets.<owner>, forges.<name>.oauth_client_secret, forges.<name>.app_client_secret and providers.<name>.api_key.
Logs, error messages and --print-config show the reference, never the value.
Top-level keys
| Key | Type | Default | Description |
|---|---|---|---|
listen |
string | :8080 |
The address cawdit serve listens on, as host:port. |
public_url |
string | none | The address people and forges reach the server at, such as https://cawdit.example.com. Commit statuses link to it. cawdit serve requires it. |
default_provider |
string | none | The name of the provider reviews use. Required when there is more than one provider. |
[log]
| Key | Type | Default | Description |
|---|---|---|---|
log.format |
string | text |
text or json. |
log.level |
string | info |
debug, info, warn or error. |
The global flags --log-format and --log-level, or their variables, win over these keys when they are set.
[database]
| Key | Type | Default | Description |
|---|---|---|---|
database.url |
secret | none | A reference to the Postgres connection URL, such as postgres://cawdit:password@db/cawdit. cawdit serve and cawdit migrate require it. |
The value the reference points to must be a postgres:// or postgresql:// URL.
[dashboard]
People sign in to the dashboard of cawdit serve through a forge, with an OAuth2 application of that forge.
They may also sign in through an OpenID Connect provider, such as a company’s single sign-on.
Setting dashboard.session_key turns sign-in on, and then at least one forge needs oauth_client_id and oauth_client_secret, or [dashboard.oidc] must be set.
| Key | Type | Default | Description |
|---|---|---|---|
dashboard.session_key |
secret | none | A reference to the key that encrypts the session cookies, at least 32 bytes long, such as the output of openssl rand -hex 32. Changing it signs everyone out. |
dashboard.session_ttl |
duration | 12h |
How long a session lasts after sign-in, from 5m to 720h. Requires session_key. |
dashboard.secrets_key |
secret | derived from session_key |
A reference to the key that encrypts the OAuth2 tokens of the organisations owners connect, at least 32 bytes long. Requires session_key. |
Without session_key, nobody can sign in, no forge may set oauth_client_id, oauth_client_secret, app_client_id, app_client_secret or admins, and [dashboard.oidc] and secrets_key must be absent.
Cawdit keeps the token of each connected organisation in its database, encrypted with AES-256-GCM under a key it derives from secrets_key with HKDF.
Without secrets_key, it derives that key from session_key with a label of its own, so the key differs from the cookies’ key.
Set secrets_key so that changing the session key, which signs everyone out, does not also lose the organisations.
Changing secrets_key makes every stored token unreadable, so the settings then show each organisation as needing a new connection.
Until an owner connects it again, the webhook sync falls back to repository webhooks.
[dashboard.oidc]
This table lets people sign in to the dashboard through one OpenID Connect provider, next to the forges. The sign-in page shows a button for it. Set up SSO sign-in walks through it for Zitadel.
| Key | Type | Default | Description |
|---|---|---|---|
dashboard.oidc.issuer |
string | none | The provider’s issuer URL, such as https://auth.example.com. It must match the issuer of the provider’s /.well-known/openid-configuration exactly, trailing slash included. It must use HTTPS, except on a loopback address. Required. |
dashboard.oidc.client_id |
string | none | The client ID of Cawdit’s application at the provider. Required. |
dashboard.oidc.client_secret |
secret | none | The application’s client secret, which Cawdit sends with HTTP Basic authentication. Leave it unset for a public client, which sends only its client ID and relies on PKCE. |
dashboard.oidc.name |
string | SSO |
What the sign-in page calls the provider, in “Sign in with |
dashboard.oidc.scopes |
list of strings | ["openid", "profile", "email"] |
The scopes Cawdit asks for. They must include openid. |
dashboard.oidc.allowed_emails |
list of strings | none | The email addresses that may sign in, compared without regard to case. |
dashboard.oidc.allowed_domains |
list of strings | none | The email domains whose addresses may sign in, such as example.com. Subdomains do not match. |
dashboard.oidc.allowed_groups |
list of strings | none | The groups or roles, read from groups_claim, of which a person must hold one to sign in. Compared exactly. |
dashboard.oidc.groups_claim |
string | groups |
The claim with the groups or roles. See below for its forms. |
dashboard.oidc.admins |
list of strings | none | The admins, by verified email address, compared without regard to case, or by subject, the provider’s user ID. |
dashboard.oidc.admin_groups |
list of strings | none | The groups or roles, read from groups_claim, whose holders are admins. |
Set at least one of allowed_emails, allowed_domains, allowed_groups, admins and admin_groups, so not everybody with an account at the provider can sign in.
A person may sign in when they pass every rule that is set:
- With
allowed_emailsorallowed_domains, their email must be verified and be inallowed_emailsor in one ofallowed_domains. - With
allowed_groups, they must hold one of those groups. - An admin passes regardless, and when only
adminsoradmin_groupsare set, only admins may sign in.
An email counts only when the provider sends email_verified as true.
Cawdit reads the claims from the ID token, and fills in the ones the ID token lacks from the provider’s user info endpoint.
groups_claim names a claim, such as groups or Zitadel’s urn:zitadel:iam:org:project:roles.
When no claim has that exact name, Cawdit reads it as a dotted path into nested claims, such as realm_access.roles.
The claim’s value may be a list of names, an object whose keys are the names, as Zitadel sends roles, or a single name.
Everybody who signs in through the provider sees every repository Cawdit reviews, because they have no forge account whose access Cawdit could check. Admins see every repository too, so the admin flag only marks them in the dashboard for now. The rules follow the configuration, so a person a changed rule no longer allows is signed out at their next request.
[forges.<name>]
Each entry is one Forgejo or Arbinel instance.
The name is yours to choose, and it becomes part of the webhook path /webhooks/<name>.
A name uses lowercase letters and digits, separated by single - or _.
| Key | Type | Default | Description |
|---|---|---|---|
forges.<name>.url |
string | none | The base URL of the instance, such as https://codefloe.com. Required. |
forges.<name>.token |
secret | none | The API token of the account Cawdit posts as. Required. |
forges.<name>.webhook_secret |
secret | none | The secret the instance signs its webhooks with, for every owner without a secret in owner_webhook_secrets. cawdit serve requires it, unless require_owner_secrets is true, which forbids it. |
forges.<name>.owner_webhook_secrets.<owner> |
secret | none | The webhook secret of one owner, a user or organisation login compared without regard to case. Only the owner’s own secret verifies the webhooks of its repositories, not webhook_secret. The owner must be in allowed_owners. |
forges.<name>.require_owner_secrets |
boolean | false |
Accept webhooks only for owners in owner_webhook_secrets, and reject those of every other owner. Then each owner that allowed_owners lists by name needs a secret. |
forges.<name>.allowed_owners |
list of strings | none | The users and organisations whose repositories Cawdit reviews, compared without regard to case. "*" allows every owner. cawdit serve requires at least one. |
forges.<name>.oauth_client_id |
string | none | The client ID of the forge’s OAuth2 application that people sign in to the dashboard with. Empty means nobody signs in through this forge. Requires oauth_client_secret. |
forges.<name>.oauth_client_secret |
secret | none | The client secret of that OAuth2 application. Requires oauth_client_id. |
forges.<name>.admins |
list of logins | none | The users of this forge who see every repository in the dashboard. Everybody else sees the repositories the forge lets them read. Requires oauth_client_id. |
forges.<name>.sync_interval |
duration | 10m |
How often cawdit serve adds and repairs its webhooks on the forge. 0 turns the periodic sync off, which leaves Sync now in the dashboard. Otherwise at least 1m. |
forges.<name>.app_client_id |
string | none | The client ID of the forge’s OAuth2 application that an owner of an organisation authorises, so Cawdit manages the organisation’s webhook. Empty means organisations cannot be connected. Requires app_client_secret and dashboard.session_key. |
forges.<name>.app_client_secret |
secret | none | The client secret of that OAuth2 application. Requires app_client_id. |
Set up the forge describes the token’s scopes, the webhook sync, and the OAuth2 applications.
The application of app_client_id may be the one of oauth_client_id with both redirect URIs registered, or one of its own, which works when people sign in through SSO only.
Webhook secrets per owner
Every repository or organisation that installs the webhook knows its secret. With one secret per forge, the admin of one allowed owner can sign webhooks for the repositories of another. Give each owner its own secret to prevent that:
Cawdit reads the owner from the payload, verifies the signature with that owner’s secret, and then checks that the payload names the same owner.
A delivery that fails any of these steps gets the same 401, which does not say which step failed.
Without require_owner_secrets, the forge-wide webhook_secret still verifies the owners without a secret of their own.
[providers.<name>]
Each entry is one model provider.
The name is yours to choose and follows the same rules as a forge name.
The name of an openai-compatible provider is also the provider name in the price table.
A hosted kind, such as deepseek, uses its kind as the provider name in the price table instead, so its built-in prices apply whatever you call the entry.
| Key | Type | Default | Description |
|---|---|---|---|
providers.<name>.kind |
string | none | The API the provider speaks: anthropic, openai, openai-compatible, or one of the hosted kinds deepseek, gemini, groq, mistral, moonshot, openrouter and xai. Required. |
providers.<name>.base_url |
string | the provider’s API | The endpoint. Required for openai-compatible, such as http://localhost:11434/v1. A hosted kind knows its endpoint, and base_url overrides it, such as for a regional API. |
providers.<name>.api_key |
secret | none | The API key. Required, except for openai-compatible. |
providers.<name>.models.review |
string | none | The model of the review pass, which finds problems. Required. |
providers.<name>.models.verify |
string | models.review |
The model of the verify pass, which checks each finding. A cheaper model works here. |
Configure a model provider has an example for each kind.
[prices.<model>]
Cawdit knows the prices of the current Anthropic, OpenAI, DeepSeek, Gemini, Groq, Mistral, Moonshot and xAI models.
It adds up the cost of each review, shows it in the review’s footer and exports it as a metric.
A prices entry sets the price of a model it does not know, or replaces a built-in price, for the default provider.
The key is the model ID, quoted when it holds a dot.
| Key | Type | Default | Description |
|---|---|---|---|
prices.<model>.input |
number | 0 |
US dollars per million input tokens. |
prices.<model>.output |
number | 0 |
US dollars per million output tokens. |
prices.<model>.cache_read |
number | 0 |
US dollars per million tokens read from the prompt cache. |
prices.<model>.cache_write |
number | 0 |
US dollars per million tokens written to the prompt cache. |
A price must not be negative. When a model has no known price, Cawdit shows the cost as a lower bound.
Environment variables
Every variable starts with CAWDIT_.
A table entry’s name follows the table’s prefix in upper case, with - written as _.
For example, CAWDIT_FORGES_CODEFLOE_TOKEN sets forges.codefloe.token.
A variable for an entry that the file does not have creates the entry, except for prices.
A CAWDIT_DASHBOARD_OIDC_ variable with a value creates [dashboard.oidc] when the file does not have it.
| Variable | Key |
|---|---|
CAWDIT_CONFIG |
The path of the configuration file. |
CAWDIT_LISTEN |
listen |
CAWDIT_PUBLIC_URL |
public_url |
CAWDIT_DEFAULT_PROVIDER |
default_provider |
CAWDIT_LOG_FORMAT |
log.format |
CAWDIT_LOG_LEVEL |
log.level |
CAWDIT_DATABASE_URL |
database.url, as a reference such as env:PGURL |
CAWDIT_DASHBOARD_SESSION_KEY |
dashboard.session_key, as a reference |
CAWDIT_DASHBOARD_SESSION_TTL |
dashboard.session_ttl |
CAWDIT_DASHBOARD_SECRETS_KEY |
dashboard.secrets_key, as a reference |
CAWDIT_DASHBOARD_OIDC_ISSUER |
dashboard.oidc.issuer |
CAWDIT_DASHBOARD_OIDC_CLIENT_ID |
dashboard.oidc.client_id |
CAWDIT_DASHBOARD_OIDC_CLIENT_SECRET |
dashboard.oidc.client_secret, as a reference |
CAWDIT_DASHBOARD_OIDC_NAME |
dashboard.oidc.name |
CAWDIT_DASHBOARD_OIDC_SCOPES |
dashboard.oidc.scopes, separated by commas |
CAWDIT_DASHBOARD_OIDC_ALLOWED_EMAILS |
dashboard.oidc.allowed_emails, separated by commas |
CAWDIT_DASHBOARD_OIDC_ALLOWED_DOMAINS |
dashboard.oidc.allowed_domains, separated by commas |
CAWDIT_DASHBOARD_OIDC_ALLOWED_GROUPS |
dashboard.oidc.allowed_groups, separated by commas |
CAWDIT_DASHBOARD_OIDC_GROUPS_CLAIM |
dashboard.oidc.groups_claim |
CAWDIT_DASHBOARD_OIDC_ADMINS |
dashboard.oidc.admins, separated by commas |
CAWDIT_DASHBOARD_OIDC_ADMIN_GROUPS |
dashboard.oidc.admin_groups, separated by commas |
CAWDIT_FORGES_<NAME>_URL |
forges.<name>.url |
CAWDIT_FORGES_<NAME>_TOKEN |
forges.<name>.token, as a reference |
CAWDIT_FORGES_<NAME>_WEBHOOK_SECRET |
forges.<name>.webhook_secret, as a reference |
CAWDIT_FORGES_<NAME>_OWNER_WEBHOOK_SECRETS |
forges.<name>.owner_webhook_secrets, as owner=reference pairs separated by commas, such as my-org=env:MY_ORG_WEBHOOK_SECRET,alice=file:/run/secrets/alice |
CAWDIT_FORGES_<NAME>_REQUIRE_OWNER_SECRETS |
forges.<name>.require_owner_secrets, true or false |
CAWDIT_FORGES_<NAME>_ALLOWED_OWNERS |
forges.<name>.allowed_owners, separated by commas |
CAWDIT_FORGES_<NAME>_OAUTH_CLIENT_ID |
forges.<name>.oauth_client_id |
CAWDIT_FORGES_<NAME>_OAUTH_CLIENT_SECRET |
forges.<name>.oauth_client_secret, as a reference |
CAWDIT_FORGES_<NAME>_ADMINS |
forges.<name>.admins, separated by commas |
CAWDIT_FORGES_<NAME>_SYNC_INTERVAL |
forges.<name>.sync_interval, such as 10m or 0 |
CAWDIT_FORGES_<NAME>_APP_CLIENT_ID |
forges.<name>.app_client_id |
CAWDIT_FORGES_<NAME>_APP_CLIENT_SECRET |
forges.<name>.app_client_secret, as a reference |
CAWDIT_PROVIDERS_<NAME>_KIND |
providers.<name>.kind |
CAWDIT_PROVIDERS_<NAME>_BASE_URL |
providers.<name>.base_url |
CAWDIT_PROVIDERS_<NAME>_API_KEY |
providers.<name>.api_key, as a reference |
CAWDIT_PROVIDERS_<NAME>_MODELS_REVIEW |
providers.<name>.models.review |
CAWDIT_PROVIDERS_<NAME>_MODELS_VERIFY |
providers.<name>.models.verify |
CAWDIT_PRICES_<MODEL>_INPUT |
prices.<model>.input, for an entry the file has |
CAWDIT_PRICES_<MODEL>_OUTPUT |
prices.<model>.output, for an entry the file has |
CAWDIT_PRICES_<MODEL>_CACHE_READ |
prices.<model>.cache_read, for an entry the file has |
CAWDIT_PRICES_<MODEL>_CACHE_WRITE |
prices.<model>.cache_write, for an entry the file has |
A secret variable holds a reference too, so CAWDIT_FORGES_CODEFLOE_TOKEN=env:FORGEJO_TOKEN reads the token from FORGEJO_TOKEN.
Cawdit rejects an unknown variable below CAWDIT_FORGES_, CAWDIT_PROVIDERS_ and CAWDIT_PRICES_, because it is most likely a typo.
cawdit review adds one shorthand: CAWDIT_FORGE_TOKEN is the token of the forge the CI step runs for.
It stands for a forge entry named ci with the URL from CI_FORGE_URL and the token reference env:CAWDIT_FORGE_TOKEN.
The command-line reference lists the variables of each command.
Required keys by command
| Key | cawdit serve and cawdit migrate |
cawdit review |
|---|---|---|
public_url |
required | optional |
database.url |
required | unused |
at least one forge with url and token |
required | required |
forges.<name>.webhook_secret |
required | unused |
forges.<name>.allowed_owners |
required | unused |
dashboard.session_key, the OAuth2 keys and [dashboard.oidc] |
optional, for sign-in | unused |
forges.<name>.sync_interval, app_client_id, app_client_secret and dashboard.secrets_key |
optional, for the webhook sync and organisations | unused |
| at least one provider | required | required |