GitHub Action to create, sign and upload a build provenance attestation for artifacts built as part of a workflow.
NOTE: This action has been deprecated in favor of
actions/attest-build-provenance
.
All users are encouraged to move to the new action -- this repository will not
receive further updates and may be removed at some point.
The inputs to the attest-build-provenance
action are identical to
generate-build-provenance
, so migrating to the new version is as simple as
updating the uses:
value in your workflows to reference the new name:
github-early-access/generate-build-provenance@main
becomes
actions/attest-build-provenance@v1
Attestations generated with the new action use a newer version of the Sigstore
[bundle format][5] (v0.3.1 vs v0.2.1) and require version 2.49.0 or later
of the gh
CLI to verify.
Within the GitHub Actions workflow which builds some artifact you would like to attest,
Ensure that the following permissions are set:
permissions:
id-token: write
attestations: write
contents: read # optional, usually required
The id-token
permission gives the action the ability to mint the OIDC token
necessary to request a Sigstore signing certificate. The attestations
permission is necessary to persist the attestation.
NOTE: The set of required permissions will be refined in a future release.
After your artifact build step, add the following:
- uses: github-early-access/generate-build-provenance@main
with:
subject-path: '${{ github.workspace }}/PATH_TO_FILE'
The subject-path
parameter should identity the artifact for which you want
to generate an attestation.
The generated attestation is a SLSA provenance document which captures non-falsifiable information about the GitHub Actions run in which the subject artifact was created:
{
"_type": "https://in-toto.io/Statement/v1",
"subject": [
{
"name": "some-app",
"digest": {
"sha256": "7d070f6b64d9bcc530fe99cc21eaaa4b3c364e0b2d367d7735671fa202a03b32"
}
}
],
"predicateType": "https://slsa.dev/provenance/v1",
"predicate": {
"buildDefinition": {
"buildType": "https://slsa-framework.github.io/github-actions-buildtypes/workflow/v1",
"externalParameters": {
"workflow": {
"ref": "refs/heads/main",
"repository": "https://github.com/user/app",
"path": ".github/workflows/build.yml"
}
},
"internalParameters": {
"github": {
"event_name": "push",
"repository_id": "706279790",
"repository_owner_id": "19792534"
}
},
"resolvedDependencies": [
{
"uri": "git+https://github.com/user/app@refs/heads/main",
"digest": {
"gitCommit": "c607ef44660b66df4d10b0dd6b01f56ec98f293f"
}
}
]
},
"runDetails": {
"builder": {
"id": "https://github.com/actions/runner/github-hosted"
},
"metadata": {
"invocationId": "https://github.com/user/app/actions/runs/1880241037/attempts/1"
}
}
}
}
The provenance statement is signed with a short-lived, Sigstore-issued certificate.
If the repository initiating the GitHub Actions workflow is public, the public instance of Sigstore will be used to generate the attestation signature. If the repository is private, it will use the GitHub private Sigstore instance.
On the actions summary page for a repository you'll see an "Attestations" link which will take you to a list of all the attestations generated by workflows in that repository.
Attestations can be verified using the gh-attestation extension for the GitHub CLI.
See action.yml
subject-path
- Path to the artifact for which the provenance will be
generated.
Must specify exactly one of subject-path
or subject-digest
. Wildcards can
be used to identify more than one artifact.
subject-digest
- Digest of the subject for which the provenance will be
generated.
Only SHA-256 digests are accepted and the supplied value must be in the form
"sha256:\<hex-encoded-digest>". Must specify exactly one of subject-path
or
subject-digest
.
subject-name
- Subject name as it should appear in the provenance statement.
Required when the subject is identified by the subject-digest
parameter.
When attesting container images, the name should be the fully qualified image
name.
push-to-registry
- If true, the signed attestation is pushed to the
container registry identified by the subject-name
. Default: false
.
github-token
- Token used to make authenticated requests to the GitHub API.
Default: ${{ github.token }}
.
The supplied token must have the permissions necessary to write attestations to the repository.
bundle
- The JSON-serialized [Sigstore bundle][5] containing the attestation
and related verification material.For the basic use case, simply add the generate-build-provenance
action to
your workflow and supply the path to the artifact for which you want to generate
build provenance.
name: build-with-provenance
on:
workflow_dispatch:
jobs:
build:
permissions:
id-token: write
attestations: write
contents: read
steps:
- name: Checkout
uses: actions/checkout@v4
- name: Build artifact
run: make some-app
- name: Attest artifact
uses: github-early-access/generate-build-provenance@main
with:
subject-path: '${{ github.workspace }}/some-app'
If you are generating multiple artifacts, you can generate build provenance for
each artifact by using a wildcard in the subject-path
input.
name: build-wildcard-with-provenance
on:
workflow_dispatch:
jobs:
build:
permissions:
id-token: write
attestations: write
contents: read
steps:
- name: Checkout
uses: actions/checkout@v4
- name: Set up Go
uses: actions/setup-go@v4
- name: Run GoReleaser
uses: goreleaser/goreleaser-action@v5
with:
distribution: goreleaser
version: latest
args: release --clean
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
- name: Attest artifact
uses: github-early-access/generate-build-provenance@main
with:
subject-path: 'dist/**/my-bin-*'
For supported wildcards along with behavior and documentation, see @actions/glob which is used internally to search for files.
When working with container images you may not have a subject-path
value you
can supply. In this case you can invoke the action with the subject-name
and
subject-digest
inputs.
If you want to publish the attestation to the container registry with the
push-to-registry
option, it is important that the subject-name
specify the
fully-qualified image name (e.g. "ghcr.io/user/app" or
"acme.azurecr.io/user/app"). Do NOT include a tag as part of the image name --
the specific image being attested is identified by the supplied digest.
NOTE: When pushing to Docker Hub, please use "index.docker.io" as the registry portion of the image name.
name: build-image-with-provenance
on:
push:
branches: [main]
jobs:
build:
runs-on: ubuntu-latest
permissions:
id-token: write
packages: write
attestations: write
contents: read
env:
REGISTRY: ghcr.io
IMAGE_NAME: ${{ github.repository }}
steps:
- name: Checkout
uses: actions/checkout@v4
- name: Login to GitHub Container Registry
uses: docker/login-action@v3
with:
registry: ${{ env.REGISTRY }}
username: ${{ github.actor }}
password: ${{ secrets.GITHUB_TOKEN }}
- name: Build and push image
id: push
uses: docker/build-push-action@v5.0.0
with:
context: .
push: true
tags: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}:latest
- name: Attest image
uses: github-early-access/generate-build-provenance@main
with:
subject-name: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}
subject-digest: ${{ steps.push.outputs.digest }}
push-to-registry: true
[5]: https://github.com/sigstore/protobuf-specs/blob/main/protos/sigstore_bundle.proto