Using artifact attestations and reusable workflows to achieve SLSA v1 Build Level 3

Note

Las atestaciones de artefactos están en versión beta pública y están sujetas a cambios.

Introduction

Artifact attestations are a great way to create unfalsifiable provenance and integrity guarantees for the software you build.

But remember that by itself, artifact attestations provides links, like the build instructions an artifact was built with, which meets SLSA v1.0 Build Level 2. To make an informed risk decision, it's up to you to follow those links and evaluate those build instructions.

You can take this a step further by requiring builds make use of known, vetted build instructions. A great way to do this is to have your build take place in a reusable workflow that many repositories across your organization share. Reusable workflows can provide isolation between the build process and the calling workflow, to meet SLSA v1.0 Build Level 3.

Before starting this guide, you should be familiar with:

Generating artifact attestations. See "Uso de atestaciones de artefactos para establecer la procedencia de las compilaciones."
Writing and using reusable workflows. See "Reutilización de flujos de trabajo."

Step 1: Configuring your builds

First, we need to build with both artifact attestations and a reusable workflow.

Building with a reusable workflow

If you aren't already using reusable workflows to build your software, you'll need to take your build steps and move them into a reusable workflow. For more information on how to write and call a reusable workflow, see "Reutilización de flujos de trabajo."

Building with artifact attestations

The reusable workflow you use to build your software must also generate artifact attestations to establish build provenance. For more information, see "Uso de atestaciones de artefactos para establecer la procedencia de las compilaciones."

When you use a reusable workflow to generate artifact attestations, both the calling workflow and the reusable workflow need to have the following permissions.

YAML

permissions:
  attestations: write
  contents: read
  id-token: write

permissions:
  attestations: write
  contents: read
  id-token: write

If you are building container images, you will also need to include the packages: write permission.

Step 2: Verifying artifact attestations built with a reusable workflow

To verify the artifact attestations generated with your builds, you can use gh attestation verify from the GitHub CLI.

The gh attestation verify command requires either --owner or --repo flags to be used with it. These flags do two things.

They tell gh attestation verify where to fetch the attestation from. This will always be your caller workflow.
They tell gh attestation verify where the workflow that did the signing came from. This will always be the workflow that uses attest-build-provenance action, which may be a reusable workflow.

You can use optional flags with the gh attestation verify command.

If your reusable workflow is not in the same repository as the caller workflow, use the --signer-repo flag to specify the repository that contains the reusable workflow.
If you would like to require an artifact attestation to be signed with a specific workflow, use the --signer-workflow flag to indicate the workflow file that should be used.

For example, if your calling workflow is ORGANIZATION_NAME/REPOSITORY_NAME/.github/workflows/calling.yml and it uses REUSABLE_ORGANIZATION_NAME/REUSABLE_REPOSITORY_NAME/.github/workflows/reusable.yml you could do:

Bash

gh attestation verify -o ORGANIZATION_NAME --signer-repo REUSABLE_ORGANIZATION_NAME/REUSABLE_REPOSITORY_NAME PATH/TO/YOUR/BUILD/ARTIFACT-BINARY

gh attestation verify -o ORGANIZATION_NAME --signer-repo REUSABLE_ORGANIZATION_NAME/REUSABLE_REPOSITORY_NAME PATH/TO/YOUR/BUILD/ARTIFACT-BINARY

Or if you want to specify the exact workflow: