Artifact Checksum Verification

---
name: artifact-checksum-verification
description: Use when 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.
license: CC-BY-4.0
metadata:
  edam_operation: http://edamontology.org/operation_3629
  edam_topics:
  - http://edamontology.org/topic_0091
  tools:
  - Semantic Release
  - shasum / sha256sum / openssl
derived_from:
- doi: 10.1021/acs.analchem.4c07078
  title: qc4metabolomics
evidence_spans: []
claims: []
provenance:
  collection: https://w3id.org/holobiomicslab/asb-skill/collection/metabolomics/v1
  assembled_by: scripts/collect_metabolomics_collection.py
  sources:
  - build: coll_qc4metabolomics
    doi: 10.1021/acs.analchem.4c07078
    title: qc4metabolomics
  dedup_kept_from: coll_qc4metabolomics
schema_version: 0.2.0
---

# 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."