Providers and credentials

Norn supports pull requests from GitHub and Bitbucket Cloud, and AI reviews through Claude or Codex.

Secret boundary

Never put tokens, usernames, or credentials in .norn.yaml, .norn.local.yaml, policy packs, prompts, or examples. Norn rejects credential-like repository configuration fields.

The desktop app stores provider credentials in the operating-system keychain. Terminal and headless workflows resolve credentials in this order:

1. OS keychain;
2. environment-variable references in ~/.config/norn/config.toml;
3. standard provider environment variables.

Environment references

Reference environment variable names without placing secret values in the file:

[credentials.github]
token_env = "GITHUB_TOKEN"

[credentials.bitbucket]
username_env = "BITBUCKET_USERNAME"
token_env = "BITBUCKET_TOKEN"

Then export the referenced variables in the shell or secret manager that starts Norn.

GitHub

GitHub needs a token with access to the repositories and pull-request actions you intend to use. The desktop GitHub App path requests read access to repository contents and metadata and read/write access to pull requests.

For terminal use, provide GITHUB_TOKEN directly or through config.toml.

Bitbucket Cloud

Bitbucket terminal authentication requires both a username and token:

export BITBUCKET_USERNAME="your-username"
export BITBUCKET_TOKEN="your-token"

Use the desktop onboarding flow when you prefer keychain-backed storage.

Claude and Codex

Norn launches the locally installed claude or codex CLI. Authenticate each provider using its own CLI before starting an AI review. norn doctor reports whether the configured provider executable is available.

Check readiness

Run a read-only diagnostic:

norn doctor --repo-path .
norn doctor --machine-only --format json

Doctor reports credential availability but never prints secret values.