Bot credentials

A Gitdown bot is a first-class principal, never a synthetic user, marketplace app, service account, or commit author. A bot has one owning subject and can have multiple grants. Each credential binds exactly one bot to exactly one grant so audit attribution never searches for “which grant won.”

Effective authority is the intersection of the active bot, credential, grant, live authorizing-subject access, recorded repository reach, requested permission or app capability, live installation state where relevant, and normal repository rules. Missing or unavailable inputs deny.

Access tokens

The credential-create response shows the bot token once with no-store headers. An exact idempotent replay returns metadata with secretUnavailable: true; it never redisplays the token. Mint separate credentials for rotation, distinct harnesses, or distinct grants.

For REST, send the token as a bot bearer only to operations whose generated contract explicitly accepts it. For Git HTTPS, use Basic username gitdown-bot. Never try a bot token as a human PAT.

Core currently maps repository metadata/browse/history to repository:read, branch list/detail to branch:read, ready/reviewer/abandon to branch:update, merge to branch:merge, bundle and LFS reads to git:fetch, and LFS uploads/lock mutations to git:push. LFS batch selects fetch or push from its request operation. These grants do not bypass visibility, collaborator roles, branch state, required checks, CAS, append-only main, validation, rate limits, or idempotency. Repository mutation, CI trigger, credential/account/org/admin surfaces, and every other unmapped operation reject bot bearers. Branch creation uses Git transport; core currently exposes no external ci:read REST route.

SSH credentials

Create the key pair outside Gitdown and enroll only the public key against one bot grant. The globally unique fingerprint resolves to the same canonical bot/grant identity used by HTTPS. Private material never crosses the API.

Rotation and revocation

Rotate by minting a new credential, switching the harness, confirming attributed use, then revoking the old credential. Revocation is terminal and idempotent. Bot disablement, grant revocation, subject access loss, repository exclusion, or installation disablement takes effect through live authorization while retaining audit history.