Add additional guidance for users who don't pin by tag (#494)

* Document the need to reference reusable workflows by tag Signed-off-by: Joshua Lock <[email protected]> * Add link to help users understand invalid builder version Signed-off-by: Joshua Lock <[email protected]> * Apply suggestions from code review Co-authored-by: Ian Lewis <[email protected]> Co-authored-by: Ian Lewis <[email protected]>
slsa-framework · Jul 6, 2022 · 8c3ab33 · 8c3ab33
1 parent 7b1729a
commit 8c3ab33
Show file tree

Hide file tree

Showing 2 changed files with 7 additions and 1 deletion.
diff --git a/.github/actions/generate-builder/builder-fetch.sh b/.github/actions/generate-builder/builder-fetch.sh
@@ -52,7 +52,8 @@ if [[ "$BUILDER_TAG" == "$(echo -n "$BUILDER_TAG" | grep -P '^[a-f\d]{40}$')" ]]
 fi
 
 if [[ "$BUILDER_TAG" != "$(echo -n "$BUILDER_TAG" | grep -P '^v\d*(\.([\d]{1,})){0,2}$')" ]]; then
-    echo "Invalid version: $BUILDER_TAG. Expected version of the form vX.Y.Z"
+    echo "Invalid builder version: $BUILDER_TAG. Expected version of the form vX.Y.Z"
+    echo "For details see https://github.com/slsa-framework/slsa-github-generator#verification-of-provenance"
     exit 7
 fi
 

diff --git a/README.md b/README.md
@@ -55,6 +55,11 @@ This is a pre-release only and we will have the official release in July 2022.
 
 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).