Gold Digger Release Process

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:

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.
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@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 (v7.0.0), actions/upload-artifact@v7.0.1, 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.

Gold Digger End-to-End Release Workflow#

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

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

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:

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

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#

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.

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@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 (v7.0.0), actions/upload-artifact@v7.0.1, 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.