How Secrets Work

A secret is a named slot that holds one credential — either a git PAT or a registry login — stored in Vault and scoped to your organization. Workflows reference a slot by name instead of carrying credentials in their config.

Slots, names, and scope

Org-scoped. A slot belongs to exactly one organization (derived from your token); cross-org access is structurally impossible. Names are unique per org.
Names. 1–64 characters of letters, digits, hyphens, and underscores. Lowercase, hyphenated names (e.g. ghcr-pull, gh-clone) read best and are the recommended convention.
One credential per slot. Each slot is exactly one type — git or registry — set when you create it.

Creating and rotating

CreateSecret is create-or-update: creating a slot with a name that already exists overwrites it in place. That is how you rotate — re-run dodil ignite secret create <name> … (or CreateSecret) with the new token, and every consumer picks up the new value the next time it resolves the slot. There’s no separate rotate call and no customer-facing version history.

The two reference fields

Consumers point at a slot through one of two string fields — both resolve against the same per-org name space:

Field	Set on	Resolved	Requires
`registry_secret_ref`	An image-mode (BYOI) app version	At deploy / cold start, to pull the private image	a `registry` slot
`secret_ref`	A git build source	At build dispatch, to clone the private repo	a `git` slot

The type must match the use: referencing a git slot as a registry_secret_ref (or vice versa) is rejected. Because resolution happens fresh each time (every cold start re-reads the registry slot; every build re-reads the git slot), a rotated value takes effect without re-deploying.

CLI consumers set these on dodil ignite draft save:


# Registry slot for a prebuilt private image
dodil ignite draft save my-app --image-ref ghcr.io/acme/app:1.2.3 --registry-secret-ref ghcr-pull
 
# Git slot for build-from-git
dodil ignite draft save my-app --git-url https://github.com/acme/app --git-secret-ref gh-clone

SecretService vs. Build secrets

Ignite has two credential stores, and they serve different roles:

SecretService slots (this service) — named, typed, referenced explicitly by registry_secret_ref / secret_ref. This is the model Compute BYOI and build-from-git use.
Build’s SaveBuildSecrets — a separate per-org store (registry creds, git creds, and build-arg secrets) applied implicitly to that org’s builds, without naming a slot.

They don’t delegate to each other. For build-from-git, the two paths converge in one resolver with a clear precedence: a named secret_ref slot wins first, then the org-level SaveBuildSecrets git credentials, then an unauthenticated (public-repo) clone.

Reading secrets back

GetSecret returns the stored value in full — slots are readable, not write-only. (ListSecrets returns metadata only — name, type, timestamps — never values.)

Security note. Because values are recoverable in cleartext by anyone in the org holding the GetSecret scope, treat scope access as access to the underlying credentials. Grant it narrowly, and rotate any token you suspect has been exposed (see Creating and rotating).

This is the opposite of Build’s build_secrets, which are redacted to *** when a build record is read back.