ru-attest-release¶
Sign build provenance for every file of a published release.
ru-attest-release.yml runs after ru-release or
ru-release-firmware (or the deprecated
ru-release-with-artifacts). It downloads the release's files, checks each against
the release's SHA256SUMS, and creates a
GitHub artifact attestation
for every file that SHA256SUMS lists: an SLSA build-provenance statement, signed through
Sigstore and stored on the repository. Anyone can then check that a file they downloaded came from this
repository's release workflow at a given commit.
It is a separate workflow because it needs id-token: write and attestations: write. GitHub refuses to start a
called workflow when any of its jobs asks for more than its caller grants, so adding the job to the release
workflows would break their existing callers.
Attestations need a public repository, or GitHub Enterprise Cloud for a private one.
Caller¶
Add a job after the release job, in the same workflow:
jobs:
release:
# ... ru-release or ru-release-firmware ...
attest:
needs: release
uses: kokeb-labs/ci-tools/.github/workflows/ru-attest-release.yml@v1
permissions:
contents: read
id-token: write
attestations: write
with:
tag_name: ${{ github.ref_name }} # or the tag the release job used
Jobs and permissions¶
| Job | Permissions | Steps |
|---|---|---|
attest (Attest release files) |
attestations: write, contents: read, id-token: write |
Download the release files and check them against SHA256SUMS; Attest every file in SHA256SUMS |
Inputs¶
| Input | Type | Default | Description |
|---|---|---|---|
tag_name |
string | empty | Tag of the published release to attest (defaults to github.ref_name) |
Check a download¶
gh release download v1.2.0 -R kokeb-labs-drivers/driver-as5047u -D v1.2.0 && cd v1.2.0
sha256sum -c SHA256SUMS
gh attestation verify as5047u-1.2.0.tar.gz -R kokeb-labs-drivers/driver-as5047u \
--signer-workflow kokeb-labs/ci-tools/.github/workflows/ru-attest-release.yml
gh attestation verify checks that the file's digest was signed by this workflow, running for that repository,
and prints the commit and the workflow run. Repeat it for each file you use.
What it proves: the release workflow of the repository published these exact files at the tagged commit. The
firmware zips are built by ru-build in CI and released by ru-release-firmware only after that CI run
passed on the tagged commit. The attestation is signed in the release job, not in the build job.
When it fails¶
| Symptom | Cause | Fix |
|---|---|---|
startup_failure |
The calling job does not grant id-token: write and attestations: write |
Grant all three permissions on the attest job |
release ... has no SHA256SUMS |
The release was made by an older ci-tools, or by hand | Release with ci-tools 1.7.0 or later |
sha256sum: WARNING ... did NOT match |
A release file was replaced after it was published | Find out who changed it; publish a new release rather than attesting a changed one |
Feature not available from the attest step |
The repository is private on a plan without attestations | Make it public, or skip this job |