Zero-friction “keyless signing” with Github Actions

In order to enable Github Actions OIDC tokens you will need to make sure your actions workflow has the following permissions: block (more info):

-- CODE language-bash -- jobs: release_job: runs-on: ubuntu-latest permissions: id-token: write # This is the key for OIDC!

The id-token: write line enables our release_job to create tokens as this workflow. It is notable that this permission may only be granted to workflows on the main repository, so it cannot be granted during pull request workflows. To facilitate OIDC support several environment variables are injected that tell the workflow how to get these tokens (read more here).

The next thing we need to do is install cosign, which is a CLI supported by the sigstore community to make signing easy. The community has an action available through the Github Action Marketplace, which can be added to your workflows via:

-- CODE language-bash -- - name: Install cosign uses: sigstore/cosign-installer@main

You can configure this to use a particular release of cosign (e.g. v1.3.1) with:

-- CODE language-bash -- - name: Install cosign uses: sigstore/cosign-installer@main with: cosign-release: 'v1.3.1'

To sign container images, the last thing we need to do is add a step that invokes the cosign CLI to sign the container image digest (replace << INSERT DIGEST >> with:

-- CODE language-bash -- - name: Sign the container image env: COSIGN_EXPERIMENTAL: "true" run: cosign sign << INSERT DIGEST >>

Note: If the image you are signing is private, then you will need to pass --force if you want to record signatures to the Rekor transparency log. Prior to cosign v1.4.x this is required for keyless signing of private images.

The most common use case here is to sign something you built earlier in the workflow, so for example using the docker/build-push-action step (e.g. id: push-step) you can use that step’s output to access the digest like this:

-- CODE language-bash -- - name: Sign the container image env: COSIGN_EXPERIMENTAL: "true" run: | cosign sign \ ${REPO}@${{ steps.push-step.outputs.digest }}

However, the docker/build-push-action currently has a bug, so you will need to add the following step earlier in your workflow to avoid this:

-- CODE language-bash -- - name: Setup buildx uses: docker/setup-buildx-action@main

-- CODE language-bash -- COSIGN_EXPERIMENTAL=true cosign verify $DIGEST | jq .

-- CODE language-bash -- Verification for $DIGEST -- The following checks were performed on each of these signatures: - The cosign claims were validated - Existence of the claims in the transparency log was verified offline - Any certificates were verified against the Fulcio roots. [ { "critical": { "identity": { "docker-reference": "ghcr.io/mattmoor/zero-friction-actions" }, "image": { "docker-manifest-digest": "..." }, "type": "cosign container image signature" }, "optional": { ... "Issuer": "https://token.actions.githubusercontent.com", "Subject": "https://github.com/mattmoor/zero-friction-actions/.github/workflows/docker-publish.yml@refs/heads/main" } } ]

In particular, note the Github Actions "Issuer", and how the "Subject" is the actions workflow used to sign the image!