Dosu Logo
Home
Documents
Gold Digger Release Process
Gold Digger Release Process
Type
Document
Status
Published
Created
Oct 31, 2025
Updated
Mar 2, 2026
Updated by
Dosu Bot

Gold Digger End-to-End Release Workflow#

This document describes the complete release workflow for Gold Digger, including cross-platform artifact creation with cargo-dist, artifact signing using GitHub attestation, SBOM generation, checksum verification, local release testing, release notes templating, and integration with automated CI/CD pipelines.

For a simplified, canonical release guide, see RELEASING.md at the repository root.

1. Cross-Platform Artifact Creation with cargo-dist#

Gold Digger uses cargo-dist to automate the creation of release artifacts for six platforms: macOS (Intel, ARM64), Linux (x86_64, ARM64), and Windows (x86_64, ARM64). Artifacts include platform-specific binaries, installers (shell, PowerShell, MSI, Homebrew), and archives (.tar.gz for Unix, .zip for Windows) DISTRIBUTION.md, dist-workspace.toml.

Configuration is managed in dist-workspace.toml:

cargo-dist-version = "0.31.0"
targets = [
  "aarch64-apple-darwin",
  "x86_64-apple-darwin",
  "aarch64-unknown-linux-gnu",
  "x86_64-unknown-linux-gnu",
  "x86_64-unknown-linux-musl",
  "aarch64-pc-windows-msvc",
  "x86_64-pc-windows-msvc",
]
installers = ["shell", "powershell", "homebrew"]
windows-archive = ".zip"
unix-archive = ".tar.xz"
github-attestations = true

Automated Release Trigger#

Releases are triggered by pushing a semantic version tag (e.g., v1.0.0). The CI pipeline builds, packages, and uploads all artifacts automatically release-runbook.md.

2. Artifact Signing with GitHub Attestation#

All release artifacts are cryptographically signed using GitHub attestation. This is enabled in dist-workspace.toml:

github-attestations = true

The release workflow generates two types of attestations for enhanced supply chain security:

  1. Build Provenance Attestation: Generated using actions/attest-build-provenance@v4, this attestation provides cryptographic proof of how artifacts were built, including the workflow, repository, and commit SHA. This enables verification of the build process and helps detect tampering.

  2. Distribution Attestation: cargo-dist automatically creates attestation files (*.intoto.jsonl) for all release artifacts, linking each artifact to its build context.

Verification can be performed using the GitHub CLI:

gh attestation verify gold_digger-v1.0.0-x86_64-unknown-linux-gnu.tar.gz --attestation gold_digger-v1.0.0-x86_64-unknown-linux-gnu.tar.gz.intoto.jsonl

Alternatively, use the GitHub web interface under the release's "Security" tab DISTRIBUTION.md, release-notes-template.md.

3. SBOM Generation#

Gold Digger generates a Software Bill of Materials (SBOM) for each release artifact using cargo-cyclonedx. SBOMs are included in CycloneDX format (.cdx.json or .cdx.xml) dist-workspace.toml, release.yml.

To inspect an SBOM:

curl -L -o sbom.json https://github.com/EvilBit-Labs/gold_digger/releases/latest/download/gold_digger-x86_64-unknown-linux-gnu.sbom.cdx.json
jq '.components[] | {name: .name, version: .version, type: .type}' sbom.json

4. Checksum Verification#

SHA256 checksums are generated for all release artifacts. To verify integrity:

curl -L -o SHA256SUMS https://github.com/EvilBit-Labs/gold_digger/releases/latest/download/SHA256SUMS
sha256sum -c SHA256SUMS --ignore-missing

DISTRIBUTION.md

5. Local Release Testing#

Before publishing a release, test the workflow locally to ensure all artifacts and installers are generated correctly.

Install cargo-dist and other tools:

cargo install cargo-dist --locked
just install-tools

Run local checks:

just dist-check # Validate configuration
just dist-plan # Show planned artifacts
just dist-build # Build artifacts locally
just dist-generate # Generate installers
just act-release-dry v1.0.0-test # Simulate release workflow locally (requires act)

CONTRIBUTING.md, release-runbook.md

6. Release Notes Templating#

Release notes are templated for consistency and automation. Gold Digger uses git-cliff to generate changelogs from conventional commits. The changelog formatting is standardized using cliff.toml cliff.toml.

Generate changelog and release notes using the justfile recipes:

just changelog v1.0.0
just release-notes v1.0.0

These recipes invoke git-cliff with the correct configuration to generate CHANGELOG.md and release-notes.md respectively.

Customize release notes using the template in release-notes-template.md. Include highlights, features, fixes, security updates, installation instructions, testing matrix, SBOM and attestation details, and checksum verification instructions.

Release notes are included in the GitHub Release via cargo-dist automation release.yml.

7. CI/CD Pipeline Integration#

Gold Digger's release workflow is fully automated using GitHub Actions. The main workflow is defined in .github/workflows/release.yml.

Key steps:

  • Triggered by semantic version tags.
  • Runs quality checks, security audits, and documentation builds.
  • Installs cargo-dist (v0.31.0) and cargo-cyclonedx.
  • Builds cross-platform artifacts and installers.
  • Generates build provenance attestations using actions/attest-build-provenance@v4.
  • Generates SBOMs and SHA256 checksums.
  • Signs artifacts with GitHub attestation.
  • Uploads and publishes artifacts to GitHub Releases.
  • Updates Homebrew tap repository for package manager distribution.

Enhanced Security Posture#

The release workflow follows security best practices:

  • Pinned Action Commits: All GitHub Actions are pinned to specific commit SHAs rather than floating version tags, ensuring reproducibility and protecting against supply chain attacks. Examples include actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd (v6.0.2), actions/upload-artifact@v7.0.0, and actions/download-artifact@v8.

  • Build Provenance: The actions/attest-build-provenance@v4 step creates verifiable attestations for all artifacts, providing cryptographic proof of the build environment and process.

  • Artifact Integrity: Multiple layers of verification (SHA256 checksums, SBOMs, and attestations) ensure artifact integrity throughout the distribution pipeline.

  • OpenSSF Scorecard: The project uses an automated OpenSSF Scorecard workflow (scorecard.yml) that runs supply-chain security checks and uploads results to GitHub's code-scanning dashboard, providing continuous monitoring of security best practices.

Local CI workflow testing is supported using act:

just act-setup
just act-ci-dry
just act-release-dry v1.0.0-test

CONTRIBUTING.md, release-runbook.md

8. Pre-Release Checklist#

Before tagging a release, ensure:

  • All quality gates pass (just ci-check)
  • All tests pass (just test)
  • Code formatting and linting are correct (just fmt-check, just lint)
  • Security audit passes (just security)
  • Documentation is up to date
  • Version number is updated in Cargo.toml
  • Changelog is generated and committed (just changelog vX.Y.Z)
  • dist-workspace.toml configuration is correct

See RELEASING.md for a concise checklist and the release-runbook.md for detailed step-by-step procedures and troubleshooting guidance.

For further details, refer to RELEASING.md for the simplified release guide, the Release Runbook for detailed procedures, DISTRIBUTION.md, and CONTRIBUTING.md.