Skip to content

release: attest build provenance for the standalone archives - #234

Open
distronode-com wants to merge 1 commit into
Calnode:mainfrom
distronode-corporation:up/release-provenance
Open

distronode-com wants to merge 1 commit into
Calnode:mainfrom
distronode-corporation:up/release-provenance

Conversation

@distronode-com

@distronode-com distronode-com commented Nov 6, 2026 •

Copy link
Copy Markdown
Contributor

Signed build provenance for the standalone release archives, attached to each release.

Why

Signed-Releases is at 0: none of the recent releases has a signature or provenance file. The archives already ship with checksums.txt, which proves a download is intact but not where it came from.

What changes

In docker-publish.yml's release job:

  • A new step runs actions/attest on dist/release/*.tar.gz before the release is created. That generates SLSA build provenance, signed through Sigstore with this workflow's identity and stored with the repository. (actions/attest-build-provenance is now a wrapper around actions/attest, which its README recommends for new setups.)
  • The Sigstore bundle is copied into dist/release/ as calnode_<version>.sigstore.json, so the existing gh release create ... dist/release/* attaches it next to the archives and checksums.txt. With the bundle, an archive can be checked from the file as well as through GitHub's attestation API.
  • The job gains id-token: write (for the Sigstore signing certificate) and attestations: write (to store the attestation). It already only runs on version tags and on the dry-run dispatch, so nothing else gets these.
  • The attestation also runs on the dry run, so the step is exercised before a real tag depends on it. A dry run's attestation records its branch rather than a release tag, so the check below does not accept it; if you would rather dry runs created none, the step can take the same if: as "Create GitHub Release".
  • If Sigstore or the attestation API is unavailable, the job fails before the GitHub Release is created, rather than publishing it without provenance. Re-running the job is enough.

DEPLOY.md's standalone-binary section gets a short "how to verify", and CHANGELOG.md an Added entry. The check that ties an archive to this workflow and its release tag is:

gh attestation verify "calnode_${version}_linux_amd64.tar.gz" --repo Calnode/calnode \
  --signer-workflow Calnode/calnode/.github/workflows/docker-publish.yml \
  --source-ref "refs/tags/v${version}"

--repo on its own accepts anything built by a workflow in this repository, dry runs included; the two extra flags narrow it to release builds. The container image is not attested here; that would be a similar step in the build job with push-to-registry, and is easy to add later if you want it.

Expected Scorecard effect

Scorecard looks at the assets of the last five releases, skipping any that have none. A release with a .sigstore.json asset scores 8 (it reserves 10 for .intoto.jsonl provenance files), so I expect Signed-Releases to rise with each release cut after this merges, reaching about 8 once the last five releases all carry a bundle. Nothing changes until the next release. This is an expectation.

How it was checked

  • The workflow parses; actionlint 1.7.12 and zizmor 1.31.1 report nothing new for docker-publish.yml. The new action is pinned to a commit SHA with its release as a comment.
  • gh attestation verify enforces --signer-workflow and --source-ref both through the API and with --bundle: checked against the GitHub CLI's own release attestations, where the matching values pass and a wrong workflow or ref fails.
  • Not run: the attest step itself. It needs the workflow's OIDC token, so it can only run on GitHub. The dry-run dispatch (dry_run: true) is the way to see it work before the next tag.

Part of a small set of Scorecard changes: #231 (token permissions), #232 (CodeQL) and #233 (pinning); discussion #235 lists the repository settings only a maintainer can change. Each stands on its own and they merge in any order.

🤖 Generated with Claude Code

The release job now runs actions/attest on dist/release/*.tar.gz before
it creates the GitHub Release. That produces SLSA build provenance,
signed through Sigstore with the workflow's identity and stored with the
repository, so anyone can check that an archive came from this workflow
and its release tag with

    gh attestation verify calnode_<version>_linux_amd64.tar.gz --repo Calnode/calnode \
      --signer-workflow Calnode/calnode/.github/workflows/docker-publish.yml \
      --source-ref refs/tags/v<version>

The Sigstore bundle is also copied into dist/release as
calnode_<version>.sigstore.json, so `gh release create ... dist/release/*`
attaches it beside the archives and checksums.txt. On a dry run the name
comes from the branch, with any slash replaced, since a slash would name
a directory.

The release job gains id-token: write (to get the Sigstore signing
certificate) and attestations: write (to store the attestation). It only
runs on version tags and on the dry-run dispatch.

The attestation runs on the dry run too, so the step is exercised before
a real tag depends on it. A dry run's attestation records its branch,
not a release tag, so the --source-ref check does not accept it.

DEPLOY.md's standalone-binary section says how to verify, and the
CHANGELOG has an Added entry.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

@pullfrog pullfrog Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

✅ No new issues found.

Reviewed changes

  • Release job permissions — id-token: write and attestations: write added alongside contents: write, each with a comment naming its consumer; the release job still only runs on refs/tags/v* or the workflow_dispatch dry run.
  • Attestation step — actions/attest pinned to the commit for v4.2.2 with subject-path: dist/release/*.tar.gz, placed after download-artifact and before the release is created, so a Sigstore failure aborts the run rather than publishing unsigned artifacts.
  • Bundle publication — the single bundle-path output is copied into dist/release/ as calnode_<version>.sigstore.json, which the existing gh release create … dist/release/* glob then attaches; GITHUB_REF_NAME#v plus slash replacement keeps the name valid for a dry-run branch ref.
  • Docs — DEPLOY.md documents gh attestation verify with --repo, --signer-workflow and --source-ref, plus the --bundle offline variant; CHANGELOG.md gets an Unreleased/Added entry pointing at the right anchor.

I checked the parts that CI cannot exercise (the release job is skipping on this PR) against upstream sources, and they hold:

  • 1e69f48acb82d1966a394da916b4c1698aa569d6 is exactly tag v4.2.2 of actions/attest.
  • bundle-path resolves to one attestation.json file even when several subjects are attested ("a single attestation will be created with references to each of the supplied subjects"), so copying a single file is right.
  • artifact-metadata: write is only required for push-to-registry; storage-record creation is gated on it, so its absence here is correct.
  • gh's --signer-workflow accepts a value with no @ref and matches a certificate from any ref, so the documented command matches tag-triggered certificates; --source-ref maps to the certificate's SourceRepositoryRef.
  • Scorecard's releasesAreSigned probe lists .sigstore.json in signatureExtensions (8 per release) while releasesHaveProvenance only recognises .intoto.jsonl, so "expect about 8" is the right expectation.

The two deliberate trade-offs called out in the description — an attestation outage blocking release creation, and dry-run attestations being accepted by a bare --repo check — are both documented in the workflow comment and DEPLOY.md rather than left implicit, which is the right handling.

Pullfrog  | View workflow run | Using deepseek-v4.1-flash | 𝕏

@shockalotti

Copy link
Copy Markdown
Contributor

Needs a rebase before this can merge. The only conflict is CHANGELOG.md; docker-publish.yml applies cleanly on top of #233, so the workflow side of this PR is fine as written.

Two things for the resolution:

  1. Put the entry under ## [Unreleased], not under ## [0.14.0]. 0.14.0 was cut on 8 Nov and its section is used verbatim as that release's published body, so an entry added there would say this shipped in a release that predates it.
  2. Rebase rather than merge. It keeps the workflow change sitting on top of ci: pin actions to commit SHAs, and the audit tools and base images to fixed versions #233 (every action pinned to a SHA, read-only permission default) and leaves the diff reviewable.

Why I am asking instead of doing it: maintainer-edit is enabled on this PR, but pushing to distronode-corporation/district-scheduler is denied for this account, so the setting does not actually help.

I did rebase it locally to check the result before asking. It comes out clean, and the release job keeps contents: write alongside the new id-token: write and attestations: write, with the steps in the right order (attest, then attach the bundle, then create the release). The only thing missing is getting that onto your branch.

Context for the conflict: 0.14.0 shipped after this was opened, and #245 replaced the frontend lockfile. Nothing here is wrong, it is just behind.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants