Implementing SHAsher in Your CI/CD Pipeline — Best Practices

Implementing SHAsher in Your CI/CD Pipeline — Best Practices

Overview

Integrate SHAsher to generate and verify content hashes at build, test, and deploy stages to ensure artifact integrity, detect accidental changes, and speed up cache layers.

Where to run SHAsher

• Build stage: create hashes for compiled artifacts and dependency bundles.
• Test stage: verify test fixtures and cached test data remain unchanged.
• Packaging stage: embed or record artifact SHAs in metadata (manifest, SBOM).
• Deploy stage: validate uploaded artifacts against recorded SHAs before release.

Pipeline layout (example)

1. Build -> 2. Generate SHA manifests -> 3. Run tests (verify hashes) -> 4. Package with manifest -> 5. Publish artifacts -> 6. Deployment verification

Best practices

• Generate immutable manifests: write a manifest file mapping artifact paths to SHAs; store alongside build outputs and in CI job artifacts.
• Use content-addressed storage: name cached artifacts by their SHAs to enable deduplication and cache hits.
• Verify on download: CI runners and deployment agents must check downloaded artifact SHAs before use.
• Sign manifests: cryptographically sign SHA manifests (CI signing key or sigstore) to prevent tampering.
• Pin hashes in deployment configs: reference specific SHAs (not just tags) for production releases.
• Fail fast on mismatch: make CI jobs fail if expected vs actual SHAs differ; surface clear error messages and links to artifacts.
• Cache smartly: combine SHAs with build inputs (source commit, tool versions) so caches are invalidated correctly.
• Store provenance: record which commit, job, and runner produced each SHA for traceability.
• Automate rotation of keys used for signing and restrict access to signing credentials.

Commands & snippets (generic)

• Generate manifest:

  Code
  Copy CodeCopied
  shasher generate –output=manifest.json dist/ 

• Verify manifest:

  Code
  Copy CodeCopied
  shasher verify –manifest=manifest.json dist/ 

• Use in CI step (pseudo):

  Code
  Copy CodeCopied
  - run: shasher generate –output=manifest.json dist/ - persist-artifacts: manifest.json 

Failure handling

• Log mismatches with file path, expected SHA, actual SHA, producing job ID, and artifact URL.
• On recurring mismatches, automate a rollback to the last-known-good SHA and create an incident.

Security considerations

• Protect signing keys and CI secrets; use short-lived credentials.
• Limit who can approve deployments that override SHA checks.
• Ensure SHA algorithm choice matches security needs (e.g., SHA-256 or stronger).

Monitoring and metrics

• Track: verification pass rate, number of mismatches, cache hit ratio, time saved from content-addressed caching.
• Alert when mismatch rate exceeds a small threshold.

Quick checklist before go-live

• Manifest generation enabled and persisted.
• Manifest signing configured.
• Verification steps added to runners and deploy agents.
• Fail-on-mismatch policy enforced.
• Provenance metadata stored with artifacts.

March 7, 2026