Update READMEs to clarify that SLSA generators and builders must be r…

…eferred 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 <[email protected]> * docs: fix grammar issue changing word 'referring' to 'referencing' Signed-off-by: Diogo Teles Sant'Anna <[email protected]> * Update README.md Signed-off-by: Ian Lewis <[email protected]> Signed-off-by: Diogo Teles Sant'Anna <[email protected]> Signed-off-by: Ian Lewis <[email protected]> Co-authored-by: Ian Lewis <[email protected]>
slsa-framework · Oct 5, 2022 · 87722f4 · 87722f4
1 parent 9dc6318
commit 87722f4
Show file tree

Hide file tree

Showing 3 changed files with 11 additions and 15 deletions.
diff --git 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
@@ -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
@@ -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