docs: add build provenance verification to the installation guide - #2473
Merged
Conversation
The attestation section PR #2352 proposed never landed, only its CI half did. Adds it with the filename mismatch already fixed: the example verifies the path the preceding manual steps actually save the binary to, rather than the release asset name.
…ance example Review follow-ups: the Windows steps move the binary into System32, so verify it there; note that gh attestation verify needs an authenticated CLI; add --signer-workflow, since --repo alone does not prove which workflow signed the attestation. The npm package does carry provenance after all, so it is pointed at npm audit signatures rather than described as unattested.
This was referenced Jul 29, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Background
Related issue: #2390
The issue was filed as "fix the filename in an existing example", but as the maintainer noted on it, that section never landed — #2352 was closed as superseded and only its CI half is on main. So this adds the section, with the mismatch already fixed.
Changes
Adds a Verify build provenance subsection to the manual-installation guide, after the checksum verification block.
The example verifies the path the preceding steps actually save the binary to —
/usr/local/bin/rulesyncon Linux/macOS,rulesync.exeon Windows — rather than the release asset namerulesync-darwin-arm64, which those steps rename away. It also states why the rename is harmless:gh attestation verifyidentifies the file by its contents, not its name.gh attestationwas introduced in GitHub CLI v2.49.0, so the minimum version is stated.Verification
I confirmed the attestation actually resolves for a renamed binary rather than assuming it. Downloading
rulesync-linux-x64from v16.0.0 as./rulesyncand querying its digest:returns a
https://slsa.dev/provenance/v1attestation whose subjects arerulesync-darwin-arm64,rulesync-darwin-x64,rulesync-linux-arm64,rulesync-linux-x64andrulesync-windows-x64.exe, built by.github/workflows/publish-assets.ymlin this repository. Lookup is by digest, so the local filename does not matter — which is what makes the corrected example valid.(The
ghin this environment is 2.46.0 and predates theattestationcommand, hence the API check rather than runninggh attestation verifyitself.)Docs-only;
skills/rulesync/installation.mdis thescripts/sync-skill-docs.tsoutput.pnpm cicheckpasses.Closes #2390