Skip to content
Cawdit

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

listen = ":8080"
public_url = "https://cawdit.example.com"
default_provider = "anthropic"

[log]
format = "json"
level = "info"

[database]
url = "env:DATABASE_URL"

[dashboard]
session_key = "file:/run/secrets/session-key"
session_ttl = "12h"
secrets_key = "file:/run/secrets/secrets-key"

[forges.codefloe]
url = "https://codefloe.com"
token = "file:/run/secrets/forge-token"
webhook_secret = "file:/run/secrets/webhook-secret"
allowed_owners = ["my-org", "alice"]
oauth_client_id = "0c3f9a51-6d2e-4b7a-9f1e-2a8d5c7b3e10"
oauth_client_secret = "file:/run/secrets/oauth-client-secret"
admins = ["alice"]
sync_interval = "10m"
app_client_id = "8d0e1f42-3b5c-4a6d-9e7f-1a2b3c4d5e6f"
app_client_secret = "file:/run/secrets/app-client-secret"

[providers.anthropic]
kind = "anthropic"
api_key = "env:ANTHROPIC_API_KEY"
models = { review = "claude-opus-5-5", verify = "claude-sonnet-5-5" }

[providers.local]
kind = "openai-compatible"
base_url = "http://ollama:11434/v1"
models = { review = "qwen3-coder" }

[prices."qwen3-coder"]
input = 0.0
output = 0.0

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:NAME reads the environment variable NAME.
  • file:/absolute/path reads 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.

[dashboard.oidc]
issuer = "https://auth.example.com"
client_id = "312345678901234567@cawdit"
client_secret = "file:/run/secrets/oidc-client-secret"
name = "Example SSO"
allowed_domains = ["example.com"]
allowed_groups = ["cawdit"]
groups_claim = "urn:zitadel:iam:org:project:roles"
admin_groups = ["cawdit-admin"]
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_emails or allowed_domains, their email must be verified and be in allowed_emails or in one of allowed_domains.
  • With allowed_groups, they must hold one of those groups.
  • An admin passes regardless, and when only admins or admin_groups are 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:

[forges.codefloe]
url = "https://codefloe.com"
token = "file:/run/secrets/forge-token"
allowed_owners = ["my-org", "alice"]
require_owner_secrets = true

[forges.codefloe.owner_webhook_secrets]
my-org = "file:/run/secrets/webhook-secret-my-org"
alice = "env:ALICE_WEBHOOK_SECRET"

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