From 87722f4064b68008ad4f0603802e52f19b5f813a Mon Sep 17 00:00:00 2001 From: Diogo Teles Sant'Anna Date: Wed, 5 Oct 2022 06:41:54 -0300 Subject: [PATCH] Update READMEs to clarify that SLSA generators and builders must be referred by tag (#957) * docs: update READMEs to clarify reference to SLSA generators and builders Previously, at some points accross the different READMEs there were explanations on why it's necessary to refer the SLSA generators and builders using tags in the format @vX.Y.Z, but some of them were incomplete. This change adds a subtopic to the base README that contains all the explanation, and this subtopic is linked on other parts of READMEs that needs the explanation. Signed-off-by: Diogo Teles Sant'Anna * docs: fix grammar issue changing word 'referring' to 'referencing' Signed-off-by: Diogo Teles Sant'Anna * Update README.md Signed-off-by: Ian Lewis Signed-off-by: Diogo Teles Sant'Anna Signed-off-by: Ian Lewis Co-authored-by: Ian Lewis --- README.md | 16 ++++++++-------- internal/builders/generic/README.md | 4 ++-- internal/builders/go/README.md | 6 +----- 3 files changed, 11 insertions(+), 15 deletions(-) diff --git a/README.md b/README.md index 76e2b21bd1..17a3f7c947 100644 --- a/README.md +++ b/README.md @@ -14,6 +14,7 @@ This repository contains the code, examples and technical design for system desc - [Roadmap](#roadmap) - [Generation of provenance](#generation-of-provenance) + - [Referencing SLSA builders and generators](#referencing-slsa-builders-and-generators) - [Builders](#builders) - [Provenance-only generators](#provenance-only-generators) - [Verification of provenance](#verification-of-provenance) @@ -42,9 +43,13 @@ timeline for completion. Below we describe the various builders and generators in this repository. They let you build and / or generate non-forgeable provenance using a trusted / isolated re-usable workflow. You can read up on the design in our [technical design document](#technical-design). -**Note**: At present the GitHub Actions provided in this repository as builders and generators **MUST** be referenced by -a tag that correpsonds to a semantic version of the form `@vX.Y.Z`. The build will fail -if you reference it via a shorter tag like `@vX.Y` or `@vX` or if you reference it by a tag of a different form (e.g., `@main`). +### Referencing SLSA builders and generators +At present, the GitHub Actions provided in this repository as builders and generators **MUST** be referenced +by tag in order for the `slsa-verifier` to be able to verify the ref of the trusted builder/generator's +reusable workflow. It also needs to be referred as `@vX.Y.Z`, because the build will fail if you reference it via a shorter tag like `@vX.Y` or `@vX`. + +This is contrary to the [GitHub best practice for third-party actions](https://docs.github.com/en/actions/security-guides/security-hardening-for-github-actions#using-third-party-actions) which recommends referencing by digest, but intentional due to limits in GitHub Actions. +The desire to be able to verify reusable workflows pinned by hash, and the reasons for the current status, are tracked as [Issue #12](https://github.com/slsa-framework/slsa-verifier/issues/12) in the slsa-verifier project. ### Builders @@ -89,11 +94,6 @@ This repository hosts the following generators: To verify the provenance, use the [github.com/slsa-framework/slsa-verifier](https://github.com/slsa-framework/slsa-verifier) project. -**Note**: At present the GitHub Actions provided in this repository as builders and generators **MUST** be referenced by tag in order for the `slsa-verifier` to be able to verify the ref of the trusted builder/generator's reusable workflow. - -This is contrary to the [best practice](https://docs.github.com/en/actions/security-guides/security-hardening-for-github-actions#using-third-party-actions) which recommends referencing by digest, but intentional due to limits in GitHub Actions. -The desire to be able to verify reusable workflows pinned by hash, and the reasons for the current status, are tracked as [Issue #12](https://github.com/slsa-framework/slsa-verifier/issues/12) in the slsa-verifier project. - ### Installation To install the verifier, see [slsa-framework/slsa-verifier#installation](https://github.com/slsa-framework/slsa-verifier#installation). diff --git a/internal/builders/generic/README.md b/internal/builders/generic/README.md index 39859394db..c86d121faf 100644 --- a/internal/builders/generic/README.md +++ b/internal/builders/generic/README.md @@ -80,8 +80,8 @@ provenance: base64-subjects: "${{ needs.build.outputs.hashes }}" ``` -**Note**: Make sure that you reference the generator with a semantic version of the form `@vX.Y.Z`. The build will fail -if you reference it via a shorter tag like `@vX.Y` or `@vX`. +**Note**: Make sure that you reference the generator with a semantic version of the form `@vX.Y.Z`. +More information [here](/README.md#referencing-slsa-builders-and-generators). Here's an example of what it might look like all together. diff --git a/internal/builders/go/README.md b/internal/builders/go/README.md index 944d08fda1..1f8c381b5d 100644 --- a/internal/builders/go/README.md +++ b/internal/builders/go/README.md @@ -128,11 +128,7 @@ The builder workflow [slsa-framework/slsa-github-generator/.github/workflows/bui Create a new workflow, e.g., `.github/workflows/slsa-goreleaser.yml`. -**Note**: Make sure that you reference the trusted builder with a semantic version of the form `@vX.Y.Z`. The build will fail -if you reference it via a shorter tag like `@vX.Y` or `@vX`. - -Referencing via hash is currently not supported due to limitations -of the reusable workflow APIs. (We are working with GitHub to address this limitation). +**Note**: Make sure that you reference the trusted builder with a semantic version of the form `@vX.Y.Z`. More information [here](/README.md#referencing-slsa-builders-and-generators). ```yaml name: SLSA go releaser