CI/CD Pipeline and Release Workflow

The automated release process is implemented using GitHub workflows and is centered around the use of cargo-dist for building, packaging, and publishing platform-specific and global artifacts. The process ensures security and compliance through artifact attestation and SBOM (Software Bill of Materials) creation, and provides robust integration with GitHub Releases, including changelog generation and prerelease handling.

Workflow Overview#

The release workflow is triggered automatically when a git tag matching a version pattern is pushed to the repository. This includes both standard releases (e.g., v1.2.3) and prerelease versions (e.g., v1.2.3-beta.1). The workflow supports both package-specific and workspace-wide releases, allowing flexibility for monorepos or multi-crate workspaces. Each tag triggers an independent workflow run, and tags with prerelease suffixes are detected and handled accordingly, marking the resulting GitHub Release as a prerelease when appropriate [libmagic-rs release.yml][StringyMcStringFace release.yml].

Building and Publishing Artifacts with cargo-dist#

cargo-dist is installed at the start of the workflow and orchestrates the entire release process. It is configured via dist-workspace.toml to build for multiple target platforms, including aarch64 and x86_64 variants for Apple Darwin, Linux (gnu and musl), and Windows MSVC. Archive formats are .tar.xz for Unix-like systems and .zip for Windows. MSVC builds use static CRT linking [libmagic-rs dist-workspace.toml][StringyMcStringFace dist-workspace.toml].

The workflow uses a matrix strategy to build platform-specific ("local") artifacts in parallel across all configured targets. A separate job builds any platform-agnostic ("global") artifacts, such as universal installers or checksums. Each build job uploads its results as workflow artifacts for later use in the release process [libmagic-rs release.yml][StringyMcStringFace release.yml].

Example snippet for installing and running cargo-dist in a workflow step:

- name: Install dist
  shell: bash
  run: "curl --proto '=https' --tlsv1.2 -LsSf https://github.com/axodotdev/cargo-dist/releases/download/v0.30.0/cargo-dist-installer.sh | sh"
- name: Build artifacts
  run: |
    dist build --output-format=json

Artifact Attestation#

Artifact attestation is performed using the actions/attest-build-provenance GitHub Action. After building the artifacts, the workflow generates provenance attestations for each artifact, providing cryptographic proof of their origin and build process. This is enabled by setting github-attestations = true in the cargo-dist configuration and is executed for each platform-specific build [libmagic-rs release.yml][StringyMcStringFace release.yml].

Example attestation step:

- name: Attest
  uses: actions/attest-build-provenance@v3
  with:
    subject-path: "target/distrib/*"

SBOM Creation#

For supply chain security and compliance, the workflow generates SBOMs using cargo-cyclonedx. This tool produces CycloneDX SBOM files (.cdx.xml), which are then moved to the distribution directory and uploaded as part of the release artifacts. SBOM generation is enabled by setting cargo-cyclonedx = true in the cargo-dist configuration [libmagic-rs release.yml][libmagic-rs dist-workspace.toml].

Example SBOM generation step:

- name: Install cargo-cyclonedx
  run: "curl --proto '=https' --tlsv1.2 -LsSf https://github.com/CycloneDX/cyclonedx-rust-cargo/releases/download/cargo-cyclonedx-0.5.5/cargo-cyclonedx-installer.sh | sh"
- name: Generate SBOM
  run: |
    cargo cyclonedx -v
    find . -name '*.cdx.xml' -exec mv '{}' target/distrib/ ';'

Changelog Generation#

Changelogs are automatically generated and included in the GitHub Release notes. This is handled by cargo-dist, which collects changelog information and provides it as part of the release metadata. The workflow uses the announcement_github_body field from the cargo-dist manifest to populate the release notes, ensuring that each release on GitHub includes a summary of changes relevant to that version [StringyMcStringFace release.yml].

Handling Prerelease Versions#

The workflow detects prerelease versions by parsing the git tag for prerelease-style suffixes (such as -alpha, -beta, or -rc). If a prerelease suffix is present, the resulting GitHub Release is marked as a prerelease. This ensures that prerelease artifacts are clearly distinguished from stable releases and can be handled differently by downstream consumers or automated tooling [libmagic-rs release.yml].

Integration with GitHub Releases#

After all artifacts are built, attested, and SBOMs generated, the workflow creates or updates a GitHub Release. All artifacts, including binaries, installers, SBOMs, and provenance attestations, are uploaded and attached to the release. The release is created with a generated title and body (including the changelog), and is marked as a prerelease if applicable. The process is fully automated and requires no manual intervention [StringyMcStringFace release.yml].

Example release creation step:

- name: Create GitHub Release
  env:
    PRERELEASE_FLAG: "--prerelease"
    ANNOUNCEMENT_TITLE: "v1.2.3"
    ANNOUNCEMENT_BODY: "Changelog and release notes here"
    RELEASE_COMMIT: "${{ github.sha }}"
  run: |
    echo "$ANNOUNCEMENT_BODY" > $RUNNER_TEMP/notes.txt
    gh release create "v1.2.3" --target "$RELEASE_COMMIT" $PRERELEASE_FLAG --title "$ANNOUNCEMENT_TITLE" --notes-file "$RUNNER_TEMP/notes.txt" artifacts/*

Additional Publishing (Homebrew)#

For projects that distribute via Homebrew, such as StringyMcStringFace, the workflow includes a job to publish or update a Homebrew formula in a separate tap repository. This job runs conditionally based on whether the release is a prerelease and user configuration [StringyMcStringFace release.yml].

This automated release process ensures that every release is reproducible, secure, and compliant, with all relevant metadata and artifacts attached to each GitHub Release. For further details, refer to the workflow and configuration files in the repository.