Federico Del Gaudio
Norn docs Providers and credentials Contents
Back to project
•
3 min read

Providers and credentials

Table of Contents

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, CLI, and Terminal UI store 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.

Terminal authentication

Inspect sanitized credential state without exposing token values or private paths:

norn auth status
norn auth status --json

Add or replace a GitHub credential with masked interactive input:

norn auth login github

Bitbucket Cloud requires a username alongside its token:

norn auth login bitbucket --username <username>

If --username is omitted during interactive login, Norn prompts for it. When using --token-stdin, pass --username explicitly because standard input is reserved for the token.

For automation, pipe the secret from your environment or secret manager through standard input instead of a command argument:

printf '%s' "$GITHUB_TOKEN" | norn auth login github --token-stdin
printf '%s' "$BITBUCKET_TOKEN" | \
  norn auth login bitbucket --username "$BITBUCKET_USERNAME" --token-stdin

Remove only the selected keychain credential with:

norn auth logout github
norn auth logout bitbucket

Norn rejects token command-line arguments so secrets do not appear in shell history or process listings.

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.

Use norn auth login github for keychain-backed terminal storage. Environment variables and config.toml references remain available as non-persisted fallbacks.

Bitbucket Cloud

Use norn auth login bitbucket --username <username> for keychain-backed storage. BITBUCKET_USERNAME and BITBUCKET_TOKEN remain available as environment fallbacks and are never silently copied into the keychain.

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.