Crate release_utils

Utilities for automatically releasing Rust code.

The intended usage is something like this (but not necessarily exactly this):

1. All code changes needed for a release are made by a developer in a regular git commit. The commit includes bumping the version in Cargo.toml, and any updates to Cargo.lock, changelog files, etc.
2. The commit message is prefixed with release: to mark the commit as a release trigger.
3. The commit is reviewed and merged through the normal pull request process.
4. Once merged, an automatic job sees the specially-marked commit and triggers any actions necessary to push the release. The building blocks for this automated part are what release-utils-rs provides.

Example code for a release job

use release_utils::release::*;
use release_utils::{get_github_sha, Package, Repo};
use std::error::Error;

/// Entry point for the auto-release process. This is intended to be run
/// from a Github Actions workflow.
fn auto_release() -> Result<(), Box<dyn Error>> {
    let commit_sha = get_github_sha()?;
    let repo = Repo::open()?;
    let commit_message_subject =
        repo.get_commit_message_subject(&commit_sha)?;

    if !commit_message_subject.starts_with("release:") {
        println!("{commit_sha} does not contain the release trigger");
        return Ok(());
    }

    Ok(release_packages(&[
        Package::new("foo"),
        Package::new("bar"),
    ])?)
}

Example Github Actions workflow

on:
  push:
    branches:
      - main

name: Release

permissions:
  contents: write

jobs:
  release:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: cargo xtask release
        env:
          CARGO_REGISTRY_TOKEN: ${{ secrets.CARGO_REGISTRY_TOKEN }}

Cargo registry token

The above Github Actions workflow requires a secret token. Generate the token in your crates.io Account Settings. The token scopes must include publish-update. If the crate has never been published before, publish-new is also required.

To make the token available to the Github Actions workflow:

1. Go to your repository’s settings
2. Click to Secrets and variables in the sidebar, then click Actions
3. Under Repository secrets, click New repository secret.

Modules

• cmd
  Utilities for running child processes.
• github
  Tools for working with the Github API.
• release
  Utilities for automatically releasing Rust code.

Structs

• CrateRegistry
  Access a crate registry.
• Package
  A package in the workspace.
• Repo
  Git repo.
• VarError
  Error getting an environment variable

Enums

• GetCrateVersionsError
  Error returned by CrateRegistry::get_crate_versions.
• GetLocalVersionError
  Error returned by Package::get_local_version.
• RepoOpenError
  Error returned by Repo::open and Repo::open_path.

Functions

• get_github_sha
  Get the commit to operate on from the GITHUB_SHA env var. When running in Github Actions, this will be set to the SHA of the commit that triggered the workflow.