Skip to content
bucker

Release attestations

A release attestation is a signed statement of what Bucker knew about one build artifact, for one commit and one environment, at one moment. Your deploy step checks it offline, with no call to Bucker, and your own policy decides what to do. A Bucker outage can neither block a deploy nor wave one through: the check Bucker posts on your pull request stays neutral, and the deploy decision is yours.

What you get

An in-toto Statement v1 in a DSSE envelope, valid for 24 hours.

  • Subject: the digest of the build artifact your CI step reported (sha256:<hex>), so an admission controller that matches on the image digest works.
  • Predicate type: https://spec.bucker.io/release-attestation/v0.1. That address names the format. It is never fetched, by Bucker or by the verifier.
  • Predicate: the signed evidence (organization, project, release, commit, environment, verdict, open-issue counts, validity window), the gates that were evaluated with their stage, revision, rule-set digest, per-rule outcomes and the digest of each signed gate result, the overrides in force named by the digest of their own receipts, and what the CI step reported about itself.
  • Signature: Ed25519 over the DSSE pre-authentication encoding, by the Bucker signing key. The same evidence is filed as a release_attestation receipt in your organization's receipt log (ledgerRef, org-log:<seq>), where bucker-verify verify-log can check it.

It carries counts, digests, identifiers and gate rule names. It carries no issue title, file name, author or override reason.

Asking for one

curl -sS -X POST "https://api.bucker.io/orgs/$ORG/projects/$PROJECT/release-attestations" \
  -H "Authorization: Bearer $BUCKER_TOKEN" -H 'content-type: application/json' \
  -d '{"sha":"'$GITHUB_SHA'","environment":"production",
       "artifactDigest":"'$IMAGE_DIGEST'","artifactName":"ghcr.io/acme/shop",
       "repository":"'$GITHUB_REPOSITORY'","ref":"'$GITHUB_REF'","workflow":"release.yml"}' \
  | jq .attestation.envelope > attestation.json

BUCKER_TOKEN is the organization CI token you already use for releases. It needs release:write, which every org CI token has; nothing about issuing widens a token. A person with write access to the project can ask too. An agent cannot, and neither can an OAuth client: an attestation is a system act after a deterministic evaluation.

Asking again for the same artifact within a minute returns the attestation already issued (reused: true). GET .../release-attestations?environment=&artifactDigest=&sha= lists a project's attestations with their status (valid, expired), and GET .../release-attestations/:id reads one.

repository, ref and workflow are what your CI step reported. They are recorded as such (reportedByCi) and proven by nothing. The keyless exchange that would prove them, trading a GitHub or GitLab workflow's OIDC token at Bucker's RFC 8693 endpoint for a short-lived token bound to repository, ref, commit, workflow and environment, is not built. It waits on the security review of the authorization server. Until then, issuing uses your CI token.

Checking one in the deploy step

Fetch the public key once, from a place you trust, and keep it with your deploy configuration:

curl -sS https://api.bucker.io/.well-known/proof-ledger-keys | jq -r .publicKeyPem > org.pem

Then, in the deploy job:

npx bucker-verify attestation attestation.json \
  --env production \
  --artifact-digest "sha256:$IMAGE_DIGEST" \
  --org "$BUCKER_ORG_ID" \
  --project "$BUCKER_PROJECT_ID" \
  --commit "$GITHUB_SHA" \
  --key org.pem

What you are deploying is not optional. --env, --artifact-digest and --org are required, and the command refuses to run without them (exit 64). A signature proves only that Bucker signed something. The signing key is Bucker's, not yours, so another organization's attestation for the same image digest carries a valid signature too. Only the digest, environment and organization you state make "is this the attestation for this deploy" answerable. Pass --project and --commit too, as above: anyone with write access to ANOTHER project of your organization can ask for an attestation of the same image digest, and only --project tells that one apart from this project's. --commit takes at least seven hex characters.

Exit Meaning
0 Signature valid under your key, and every claim holds.
2 No key you supplied verifies the signature: the attestation was altered or signed by another issuer.
4 The signature holds but the attestation does not say what this deploy needs. The finding code says which.
6 Not a release attestation, or malformed.
7 No key was supplied. Nothing was checked, so nothing is accepted.
64 Usage error.

Finding codes under exit 4: EXPIRED, NOT_YET_VALID, VALIDITY_TOO_LONG, WRONG_ARTIFACT, SUBJECT_MISMATCH, WRONG_ENVIRONMENT, WRONG_ORG, WRONG_PROJECT, WRONG_COMMIT, VERDICT_NOT_ACCEPTED. Run with --json to read them. --now <ISO time> fixes the clock for a reproducible check. The command imports no network module and reads the clock in one place, the default of --now.

The verdict, and whose policy it is

Over the project's gates that cover a deploy, evaluated when you ask:

Verdict When
blocked An enforced gate failed and no override covers it.
not_evaluated No enforced gate of this project covers a deploy (shadow and warn gates alone decide nothing, pass or fail), an enforced gate could not decide (missing data), or an enforced gate could not be read.
attention Every enforced gate passed or is covered by an override in force, and a warn or shadow gate failed or an override was needed.
clear At least one enforced gate passed and nothing failed.

Bucker never refuses to issue because of the verdict: it states the fact. By default the verifier accepts clear and attention and refuses blocked and not_evaluated (VERDICT_NOT_ACCEPTED). --accept-verdict clear is stricter; --accept-verdict clear,attention,not_evaluated is looser. An override is never reported as clear: Bucker does not claim a pass it did not compute. An override counts only when it has a signed receipt, so it can be named by digest, and only while the gate is at the revision the person overrode: editing the gate ends the override's effect on attestations.

openIssues counts the project's issues that are new, ongoing or regressed. newIssuesSinceBaseline counts those first seen after the baseline, the most recent earlier deploy of this project to the same environment. With no earlier deploy it is 0 and the predicate's baseline is null.

Offline revocation

Validity is short on purpose: an attestation is stale after 24 hours whatever happens. Revoking one before then (a person's act) and listing revoked attestations in the checkpoint are not built yet; a verifier that must honour a revocation sooner than the window ends needs to fetch the status, which this offline command deliberately does not do.

Kyverno and Sigstore policy-controller

The subject digest is the artifact's, so an ImageVerification / ClusterImagePolicy attestation rule can select the statement by predicateType and read predicate.evidence.verdict, predicate.evidence.validUntil and predicate.evidence.environment in a CEL or JMESPath condition. Distribute the Bucker public key as the policy's key.

What is held

  • The keyless workflow-identity exchange (OIDC at the RFC 8693 endpoint). No route exists for it.
  • Which key signs releases: today the proof-ledger signing key does. A dedicated release key, or a key per organization, is the owner's decision (H-409). Until then the organization check above is what separates one tenant's attestations from another's.