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.