feat(p5): add verify-the-release guide#21
Open
rocklambros wants to merge 1 commit into
Open
Conversation
P5 Task 128. Documents the sigstore-verify workflow users run to verify a CSCR release tarball before trusting the plugin. Content lifted verbatim from the Task 128 inline spec. Honest framing preserved: - "What this verifies" enumerates the three things the signature proves - "What this does NOT verify" enumerates the four things it does NOT (signing-time account compromise, content accuracy, user-authored hooks, and is explicit about Rekor as the post-hoc detection mechanism for the first) - Co-signing acknowledged as a v2.2.0 milestone, not a v2.0.0 property Forward references to: - docs/how-to/audit-cscr-pre-trust.md (separate doc, not yet written) - docs/governance.md (exists, contains the co-signing roadmap)
Contributor
There was a problem hiding this comment.
Pull request overview
Adds end-user documentation for verifying CSCR release tarballs with sigstore before trusting/using the plugin, aligning with the P5 “honest framing” approach around what verification does and does not guarantee.
Changes:
- Adds a new how-to guide for verifying a release tarball using
python -m sigstore verify identity. - Documents the expected verification outcome plus explicit “verifies” vs “does NOT verify” boundaries.
- Notes the co-signing plan and points readers to governance for roadmap details.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| ## Prerequisites | ||
|
|
||
| ```bash | ||
| pip install sigstore |
Comment on lines
+36
to
+37
| - That the skill content is accurate. (No mechanism can verify accuracy; see `docs/how-to/audit-cscr-pre-trust.md` for the manual six-check audit.) | ||
| - The user-authored hooks you wrote from `docs/how-to/write-your-own-hook.md`. (Those are your code; verify them yourself.) |
Comment on lines
+33
to
+38
| ## What this does NOT verify | ||
|
|
||
| - That Rock's GitHub account was not compromised at signing time. (Mitigated by sigstore's transparency log — a compromised signing is detectable post-hoc via Rekor.) | ||
| - That the skill content is accurate. (No mechanism can verify accuracy; see `docs/how-to/audit-cscr-pre-trust.md` for the manual six-check audit.) | ||
| - The user-authored hooks you wrote from `docs/how-to/write-your-own-hook.md`. (Those are your code; verify them yourself.) | ||
|
|
3 tasks
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
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.
Summary
P5 Task 128 deliverable. New file
docs/how-to/verify-the-release.mddocumenting how users verify a CSCR release tarball with sigstore before trusting the plugin. Content lifted verbatim from the Task 128 inline spec in the implementation plan.The guide is short (41 lines) and sticks to the honest-framing pattern established by the rest of P5:
Test plan
python -m sigstore verify identitysignatureForward references
docs/how-to/audit-cscr-pre-trust.md— not yet written; planned for a separate PRdocs/governance.md— exists in the repoReviewer
@fewdisc — small doc, verbatim from the plan spec. Worth verifying the sigstore command syntax is current (the plan was drafted before sigstore's 3.x release; if their CLI changed I'd want to know now rather than at v2.0.0 tag time).
Related