Verifying Releases

How to verify a DispatchAtlas release — the single audited workflow that builds, signs, and attests every release candidate, and how to check its provenance.

Every DispatchAtlas release candidate is built by a single audited workflow that emits, alongside the Python distributions, a set of independently verifiable supply-chain artifacts: SHA-256 hashes, Sigstore signature bundles, GitHub build provenance attestations, an SBOM attestation, and a CycloneDX software bill of materials. This page documents how to verify each one.

Replace vX.Y.Z with the release tag you downloaded throughout.

📦 Artifacts attached to a release

Artifact	Purpose
`.whl`, `.tar.gz`	Python wheels and source distributions.
`SHA256SUMS.txt`	SHA-256 hashes for every distribution artifact.
`*.sigstore.json`	Sigstore signature bundle (one per artifact).
`sbom.cyclonedx.json`	CycloneDX SBOM of the audited build environment.

GitHub build provenance and SBOM attestations are stored with the repository's attestation records rather than as release attachments, and are verified through the GitHub CLI.

🔢 Verify the hashes

Download the distribution artifacts and SHA256SUMS.txt into the same directory, then check them:

sha256sum --check SHA256SUMS.txt

Every line must report OK.

✍️ Verify the Sigstore signatures

The release signs each artifact with keyless Sigstore signing through the workflow's OpenID Connect identity. Install cosign and verify the bundle for an artifact:

cosign verify-blob \
  --bundle dispatchatlas-vX.Y.Z-py3-none-any.whl.sigstore.json \
  --certificate-identity-regexp 'https://github.com/ahmed-g-gad/dispatchatlas/.*' \
  --certificate-oidc-issuer https://token.actions.githubusercontent.com \
  dispatchatlas-vX.Y.Z-py3-none-any.whl

A successful run prints Verified OK. The same command verifies SHA256SUMS.txt and sbom.cyclonedx.json against their bundles.

🧾 Verify the GitHub build provenance

Each distribution carries a signed provenance statement describing the workflow, commit, and runner that built it. Verify it with the GitHub CLI:

gh attestation verify dispatchatlas-vX.Y.Z-py3-none-any.whl \
  --repo ahmed-g-gad/dispatchatlas

The output confirms the artifact was built by the release workflow at the expected commit.

🧰 Inspect the SBOM

The CycloneDX SBOM enumerates every component in the build environment with its package URL, license, and content hashes. Inspect it with any CycloneDX-aware tool, or read the component list directly:

python -c "import json; d = json.load(open('sbom.cyclonedx.json')); \
print('\n'.join(c['name'] + ' ' + c.get('version', '') for c in d['components']))"

The SBOM is itself attested; verify the SBOM attestation with:

gh attestation verify dispatchatlas-vX.Y.Z-py3-none-any.whl \
  --repo ahmed-g-gad/dispatchatlas \
  --predicate-type https://cyclonedx.org/bom

🚨 Reporting a verification failure

If any verification step fails for an artifact you downloaded from an official release, do not install it. Report the discrepancy through the channels in the project security policy.