Write one page that tells users exactly how to check a download: where to get your key or signing identity, the commands to run, and what a good result looks like. If users cannot verify without guessing, signing protects almost nobody.
What the page needs
- What is signed. Tags, files, checksum list, container images.
- Who signs. A key fingerprint, or for keyless signing the identity and issuer to expect.
- Where to get the key. Several places, so a change in one is noticed.
- Commands, copy ready.
- What a good result looks like, and what to do on a bad one.
- Key history. Past keys and the releases they covered. See what to do when your release signing key expires.
Commands to include
For git tags, the verify option of git tag checks the tag signature:
git tag -v v2.4.0
For a checksum list, the sha256sum manual describes a check option that reads checksums from files and verifies them:
sha256sum --check --ignore-missing SHA256SUMS
For files signed with cosign, the Sigstore documentation shows a verify blob command that takes a bundle file plus the expected certificate identity and issuer:
cosign verify-blob myfile --bundle myfile.sigstore.json \
--certificate-identity=name@example.com \
--certificate-oidc-issuer=https://accounts.example.com
Replace the placeholder identity and issuer with your project's real values. See the next post, what certificate identity and issuer mean when you verify a release.
Layout that works
| Section | Contents |
|---|---|
| Quick verify | The three commands above for the current release |
| Keys and identities | Fingerprints, identity strings, where else they are published |
| Troubleshooting | Common failure messages and what they mean |
| History | Previous keys, revocations, dates |
Testing your own page
Follow it on a clean machine, as a new user would. Fix every place you had to improvise. Re-run it after each key change.
Keep it honest
Say what verification proves and what it does not. A good signature shows who signed, not that the code is free of bugs. Mention other checks users can run, such as scanning the dependencies listed in your SBOM.
Try it yourself
Click through it at your own pace, or open it full screen.
Open a component and see the dependency detail a user can inspect after verifying your release files.
Common failure messages to document
Users will hit errors, and a page that explains them saves support time. List the likely ones: a missing public key, an expired key, a checksum mismatch, a signature that does not match the file, and an identity that does not match the expected value. For each, say what it usually means and what to do. A mismatch after a fresh download usually points to a corrupted or incomplete download first, so suggest retrying from the official location before raising an alarm. If it persists, give a way to contact the maintainers privately.
Quick check
Where should the verify page live?
On your own site and also in the repository, so the two can be compared. Link to it from every release.
Do I need all three methods?
No. Use the ones your project actually publishes, and say which.
Sources
Last reviewed: 19 October 2026.
