Skip to content

List publishers in the index

List the identities that sign a package’s releases in its root document, so a client verifies them with no operator configuration.

Declare publishers in the index

A package’s root document can list who signs its releases, in a publishers array. The list lives in the index, so it reaches a client with the root and needs no operator configuration. Before a pull, OCX reads the committed root and checks the release signature against the list: the signature must match at least one entry. A package that lists no publishers is verified only if an operator [[trust.policy]] covers it. Under signatures = "required", such a package is refused instead.

The index maintainer adds the array to the package’s root document in the index repository. Publishers do not set it with a command.

Each entry names a kind:

{
"publishers": [
{
"kind": "keyless",
"oidc_issuer": "https://token.actions.githubusercontent.com",
"claims": {
"build_signer_uri": "https://github.com/acme/release/.github/workflows/publish.yml@refs/heads/main",
"source_repository_identifier": "123456789"
}
},
{ "kind": "key", "key_pem": "-----BEGIN PUBLIC KEY-----\n...\n-----END PUBLIC KEY-----\n" }
]
}

A keyless entry requires oidc_issuer and at least one of identity, identity_regexp (not both) or a non-empty claims object. A key entry carries the public key inline as key_pem. A remote document never names a local file, so a key field is invalid.

Each element of the array is classified on its own:

Entry Outcome
Not an object, no string kind, or the list is not a non-empty array Invalid
kind other than keyless or key, or a field outside the kind’s set Unrecognised: the entry is skipped, since a newer OCX may understand it
keyless without oidc_issuer, with both identity and identity_regexp, with no identity rule, a non-string value, or an identity_regexp that does not compile Invalid
key with a key field, without key_pem, or a key_pem that does not parse Invalid
key_pem of a key type OCX does not support Unrecognised
Everything else Usable

Usable entries are alternatives. If none is usable, OCX refuses the install: publishers_unrecognized (exit 82) when any entry was unrecognised, publishers_invalid (exit 65) when all were invalid.

Claims

The signing certificate carries the workflow context as Fulcio extensions. claims matches them by name, or by dotted OID inside 1.3.6.1.4.1.57264.1.. Every listed claim must match, and a claim the certificate does not carry never matches. A dotted key outside that arc is invalid, and an unknown name is unrecognised, so the entry matches nobody under this OCX version.

Common claim names are build_signer_uri, source_repository_identifier and build_signer_digest.

Pair build_signer_uri with source_repository_identifier. The first names the workflow file and ref that signed. The second is the numeric repository ID, which survives a repository rename or transfer where the owner/name form does not. For a reusable workflow, build_signer_uri names the called workflow, so build_signer_digest pins the commit of that workflow.

Registry policy

The signatures setting under [registries.<name>] decides what happens around the list:

Value Behavior
if_declared (default) Verify when the root lists publishers; otherwise fall through to operator policy.
required Refuse a package whose root lists no publishers (publishers_required, exit 81).
off Ignore publishers for this registry.

An unknown value behaves as required and logs one warning.

An operator [[trust.policy]] signer takes the same claims table, under the same rules.

When no listed publisher signed the release, the install fails with publisher_mismatch (exit 77). Install a release a listed publisher signed, run ocx index update <package> to refresh the root, or pass --no-verify.

The other refusals have their own remedies. publishers_required is cleared by loosening signatures or passing --no-verify. publishers_unrecognized is cleared by upgrading OCX or setting signatures = "off". A publishers_invalid refusal is a defect in the index entry for its publishers to fix.