CI/CD for a Rust cargo-dist Release with GitHub Actions

Build cross-platform Rust binaries and shell/PowerShell installers on a tag.

cargo-dist generates a release workflow that builds your Rust binary for many targets and produces shell and PowerShell installers plus archives. This recipe shows the generated workflow and how to regenerate it.

What the pipeline does

• trigger on a v* tag
• plan the release across configured targets
• build artifacts per platform in a matrix
• generate installers and a manifest
• publish everything to the GitHub release

The workflow

cargo dist init writes .github/workflows/release.yml. You configure targets and installers in Cargo.toml under [workspace.metadata.dist]; regenerate after changes with cargo dist generate.

name: Release
on:
  push:
    tags: ["v*"]
permissions:
  contents: write
jobs:
  build:
    strategy:
      matrix:
        include:
          - os: ubuntu-latest
            target: x86_64-unknown-linux-gnu
          - os: macos-latest
            target: aarch64-apple-darwin
          - os: windows-latest
            target: x86_64-pc-windows-msvc
    runs-on: ${{ matrix.os }}
    steps:
      - uses: actions/checkout@v4
      - uses: dtolnay/rust-toolchain@stable
        with:
          targets: ${{ matrix.target }}
      - uses: Swatinem/rust-cache@v2
      - run: cargo install cargo-dist --locked
      - run: cargo dist build --target ${{ matrix.target }}
      - uses: actions/upload-artifact@v4
        with:
          name: dist-${{ matrix.target }}
          path: target/distrib/*

Caching and speed

Swatinem/rust-cache caches the registry and target dir per OS. The matrix builds on Linux, macOS, and Windows at once; on macOS and Windows in particular, cheaper managed runners such as Latchkey (around 69% cheaper than GitHub-hosted) trim the biggest line items, and auto-retry covers a flaky cross toolchain fetch.

Deploying

A final job collects the per-target artifacts, generates the shell and PowerShell installers and a dist-manifest.json, and uploads them to the GitHub release for the tag. Users install with the one-line script cargo-dist prints.

Key takeaways

• cargo-dist generates the whole release workflow from Cargo.toml config.
• Build a matrix across Linux, macOS, and Windows targets.
• It produces shell and PowerShell installers plus a manifest, not just archives.

Related guides