docs: add commands for artifact verification using GitHub Attestations (#1500)

shaanmajid · web-flow · commit 7e1a49701c67 · 2026-01-31T13:34:54.000+08:00
Document how to verify release artifacts and Docker images using `gh attestation verify`. Refs: #1494, #1497
diff --git a/docs/installation.md b/docs/installation.md
@@ -93,3 +93,23 @@ COMPLETE=fish prek > ~/.config/fish/completions/prek.fish
 ```powershell
 COMPLETE=powershell prek >> $PROFILE
 ```
+
+## Artifact Verification
+
+Release artifacts are signed with
+[GitHub Attestations](https://docs.github.com/en/actions/security-for-github-actions/using-artifact-attestations)
+to provide cryptographic proof of their origin. Verify downloads using the
+[GitHub CLI](https://cli.github.com/):
+
+```console
+$ gh attestation verify prek-x86_64-unknown-linux-gnu.tar.gz --repo j178/prek
+Loaded digest sha256:xxxx... for file://prek-x86_64-unknown-linux-gnu.tar.gz
+Loaded 1 attestation from GitHub API
+✓ Verification succeeded!
+
+- Attestation #1
+  - Build repo:..... j178/prek
+  - Build workflow:. .github/workflows/release.yml@refs/tags/vX.Y.Z
+```
+
+This confirms the artifact was built by the official release workflow.
diff --git a/docs/integrations.md b/docs/integrations.md
@@ -23,6 +23,29 @@ If you prefer, you can also run the distroless image directly:
 docker run --rm ghcr.io/j178/prek:v0.3.0 --version
 ```
 
+### Verifying Images
+
+Docker images are signed with
+[GitHub Attestations](https://docs.github.com/en/actions/security-for-github-actions/using-artifact-attestations)
+to verify they were built by official prek workflows. Verify using the
+[GitHub CLI](https://cli.github.com/):
+
+```console
+$ gh attestation verify --owner j178 oci://ghcr.io/j178/prek:latest
+Loaded digest sha256:xxxx... for oci://ghcr.io/j178/prek:latest
+Loaded 1 attestation from GitHub API
+✓ Verification succeeded!
+
+- Attestation #1
+  - Build repo:..... j178/prek
+  - Build workflow:. .github/workflows/build-docker.yml@refs/tags/vX.Y.Z
+```
+
+!!! tip
+
+    Use a specific version tag (e.g., `ghcr.io/j178/prek:v0.3.0`) or image
+    digest rather than `latest` for verification.
+
 ## GitHub Actions
 
 --8<-- "README.md:github-actions"
