Artifact checksum verification

artifact-checksum-verification

Summary

Verify that versioned release artifacts match their reference checksums and metadata by comparing generated files against a trusted GitHub release record. This ensures reproducibility of automated release processes and detects corruption or tampering.

When to use

When reproducing a prior software release (especially one generated by automated versioning tools like Semantic Release), you need to confirm that the artifacts produced in your environment match the original release byte-for-byte. Apply this skill after regenerating release artifacts from a git tag to validate that your build environment and configuration produce identical outputs.

When NOT to use

• You are validating a first-time release for which no prior reference release exists — use initial artifact publication and checksumming instead.
• The artifacts are from different major versions or build configurations — checksum matching is only meaningful for identical release contexts.
• You lack access to the authoritative GitHub release record or cannot retrieve its checksums — defer verification until the reference is available.

Inputs

• GitHub release record with artifact metadata and checksums
• Generated release artifacts (binary archives, source tarballs, compiled binaries, documentation)
• Git repository at specific version tag (e.g., v1.0.0)
• Release configuration files (e.g., semantic-release config)

Outputs

• Validation report: checksum match/mismatch status per artifact
• Version number verification result
• File content equivalence assessment
• Summary of discrepancies (if any) with root cause analysis

How to apply

Retrieve the reference release metadata and artifact checksums from the authoritative GitHub release record (e.g., dated 2025-07-29 for QC4Metabolomics v1.0.0). Generate or obtain the candidate artifacts in your environment (via Semantic Release or equivalent tooling). Compute cryptographic hashes (typically SHA-256 or MD5) for each candidate artifact using standard tools (shasum, sha256sum, openssl dgst, or language equivalents). Compare the computed hashes line-by-line against the reference checksums; additionally verify version numbers embedded in filenames and release notes, and inspect file contents for semantic equivalence if hashes diverge. Document any mismatches as build environment, configuration, or timestamp discrepancies.

Related tools

• Semantic Release (Automated tool that generates versioned release artifacts, version numbers, and release notes; outputs are the artifacts to be verified against reference checksums) — https://github.com/semantic-release/semantic-release
• shasum / sha256sum / openssl (Command-line tools to compute cryptographic hashes of candidate artifacts for comparison against reference checksums)

Examples

sha256sum -c <(curl -s https://api.github.com/repos/stanstrup/QC4Metabolomics/releases/tags/v1.0.0 | jq -r '.assets[] | "\(.browser_download_url) \(.name)"' | while read url name; do curl -sL $url | sha256sum; done)

Evaluation signals

• All artifact checksums (SHA-256 or equivalent) match the reference GitHub release record exactly
• Version number in artifact filenames and metadata matches the git tag and reference release
• File counts and names match between generated and reference releases
• Release notes or version strings embedded in artifacts are identical to the reference
• No byte-level differences detected when checksums diverge (validate root cause: timestamps, build environment, dependencies)

Limitations

• Checksum matching is sensitive to build environment (compiler versions, timestamps, locale settings); identical source may produce different binaries across platforms or tool versions.
• Metadata files (release notes, changelogs) may differ in whitespace or line endings despite semantic equivalence; byte-level comparison may fail where semantic validation would succeed.
• No verification of the reference GitHub release record itself — assumes the reference is authoritative and uncorrupted.

Evidence

• [other] Validate the generated release artifacts and metadata against the reference GitHub release record dated 2025-07-29 to confirm version number, file contents, and checksums match.: "Validate the generated release artifacts and metadata against the reference GitHub release record dated 2025-07-29 to confirm version number, file contents, and checksums match."