Skip to content

Release Automation

Shaken Fist Python projects use a standardised release workflow based on GitHub Actions, PyPI trusted publishers, and Sigstore signing. This page describes the release infrastructure and how to add it to a new project.

How It Works

When a maintainer pushes a git tag matching v* (e.g. v0.6.0), the release.yml workflow:

  1. Checks CI with ci-gate, which fails unless the repository's named CI workflows succeeded on the tagged commit (see require-ci-success)
  2. Builds the package using python3 -m build in a clean venv
  3. Validates the package with twine check, and checks the wheel holds no test directory with check-dist
  4. Waits for approval from a required reviewer (via a GitHub environment)
  5. Signs the tag using Sigstore/gitsign (keyless, OIDC-based)
  6. Publishes to PyPI using trusted publishers (no API tokens)
  7. Creates a GitHub Release with the built artifacts and auto-generated release notes

The release job downloads the distribution to a named path and sets fail_on_unmatched_files, so that a release which attaches nothing fails rather than reporting success. Both are load bearing: with a bare download and the action's default of warning on an unmatched glob, an empty release is indistinguishable from a good one.

The workflow can also be started by hand, which skips ci-gate, runs the build, the twine check and the wheel check as a smoke test, and stops there. Everything from the tag signing down is confined to a pushed tag with if: github.event_name == 'push' && startsWith(github.ref, 'refs/tags/v'). Both clauses are needed: aimed at a branch, an unguarded sign-tag would take refs/heads/<branch> for a tag name and force-push refs/tags/refs/heads/<branch>; aimed at an existing tag, a ref-only guard would let the run re-sign and force-push that tag, rewriting a signed object someone may already have verified. Re-running a failed release still works, because "Re-run jobs" replays the original push event.

These runners are persistent and download-artifact extracts into its target rather than replacing it, so a publishing job must not read a directory an earlier job may have left files in. The two jobs solve that differently. publish-pypi checks out, which cleans the workspace with git clean -ffdx, and works in dist/ -- it has to, because pypa/gh-action-pypi-publish delegates to a Docker container action, and the container is given RUNNER_TEMP at /github/runner_temp while ${{ runner.temp }} expands to the host path, which is not there. github-release runs a JavaScript action on the host, so it skips the checkout and downloads into the per-job ${{ runner.temp }} instead.

flowchart TB
    tag["Maintainer pushes v0.6.0 tag"]
    gate["Check CI passed on the tagged commit"]
    build["Build and check package"]
    artifacts["Upload artifacts"]
    approve["Wait for reviewer approval<br/>(GitHub environment)"]
    sign["Sign tag with Sigstore"]
    pypi["Publish to PyPI"]
    release["Create GitHub Release"]

    tag --> gate
    gate --> build
    build --> artifacts
    build --> approve
    approve --> sign
    sign --> pypi
    pypi --> release

Security Properties

The release process is designed to eliminate long-lived secrets:

  • No PyPI API tokens -- authentication uses OIDC trusted publishers, where PyPI verifies the GitHub Actions workflow identity directly
  • No GPG keys -- tag signing uses Sigstore's keyless signing with OIDC identity certificates, recorded in the Rekor transparency log
  • Tested commits only -- ci-gate refuses a tag on a commit whose CI did not pass, before anything is built, so a reviewer approves a release whose CI has already been checked
  • Multi-party approval -- the release environment requires a reviewer to approve before publishing proceeds
  • Protected tags -- tag rulesets prevent unauthorized users from creating release tags
  • Build provenance -- Sigstore attestations cryptographically link published artifacts to the exact source commit

Adding Release Automation to a Project

Prerequisites

The project must:

  • Use pyproject.toml with setuptools_scm (or similar) for version detection from git tags
  • Not have an old release.sh script (remove it first)
  • Run CI in a way the release gate can count: see "Prerequisites for gated CI" in the template README

Step 1: Copy the Templates

Templates are in templates/release-automation/:

Template Destination
release.yml .github/workflows/release.yml
RELEASE-SETUP.md RELEASE-SETUP.md (repo root)

Replace the placeholders in the copied files:

Placeholder Description Example
{{PROJECT_DISPLAY_NAME}} Human-readable name Occy Strap
{{PYPI_PACKAGE_NAME}} PyPI package name occystrap
{{GITHUB_REPO_NAME}} GitHub repo name occystrap
{{CI_WORKFLOWS}} CI workflow files the release gate requires, one per line ci.yml

Step 2: Configure PyPI Trusted Publisher

  1. Log in to pypi.org
  2. If the package has never been published, there is no project to scope a publisher to: add a pending publisher from https://pypi.org/manage/account/publishing/ instead, which also asks for the PyPI project name and becomes an ordinary trusted publisher on the first upload. Otherwise, navigate to your project's Publishing settings
  3. Add a trusted publisher:
  4. Owner: shakenfist
  5. Repository: your repo name
  6. Workflow: release.yml
  7. Environment: release

A wrong value here only fails at publish-pypi, after sign-tag has already pushed the signed tag, so the recovery is the next version rather than a re-pushed tag.

Step 3: Create GitHub Environment

  1. Go to Settings > Environments in the repository
  2. Create an environment named release
  3. Add required reviewers
  4. Restrict deployment to tags matching v*

Step 4: Configure Protected Tags

  1. Go to Settings > Rules > Rulesets
  2. Create a tag ruleset for v* restricting creation, deletion and force pushes
  3. Add maintainers to the bypass list, and not GitHub Actions: sign-tag collides with none of those rules, so the bypass would only let every workflow create and delete release tags

Tag updates stay unrestricted, so anyone with write access can rewrite a released tag. RELEASE-SETUP.md step 3 explains why the fleet accepts that gap rather than close it with Restrict updates.

Step 5: Remove Old Release Scripts

Delete any existing release.sh and commit the removal.

Rust Projects

ryll, instar and andris release from templates/release-automation-rust/ instead. It keeps the same CI gate, signing and guards, and adds two scripts: one proposes the version bump as a pull request through the merge queue, and the other tags the commit that merged it. Its README lists the invariants every Rust release keeps, and how each of the three repositories fills the workflow's build section.

Projects Using This Infrastructure

Project PyPI Package Status
shakenfist shakenfist Live
occystrap occystrap Live
kerbside kerbside Live
agent-python shakenfist-agent Added

Recovering a Failed Release

A release can fail after it has already published something. The policy is burn the version and tag the next one: do not try to replace a version an index has already served. PyPI never lets a file be re-uploaded, so a "fixed" re-release of the same version is not possible even in principle.

Re-running the workflow is safe, and is how you finish a release that failed partway. publish-pypi passes skip-existing: true, so a job that reaches a version PyPI already holds reports success and lets the jobs behind it run. Without it the release deadlocks, because github-release has publish-pypi in its needs list: once PyPI has the version, every later run fails in publish-pypi and everything downstream skips. That is what made shakenfist/client-python-k3s#168 unfixable by re-running — the plugin was on PyPI, its Ansible collection was never published, and the workflow could not be driven past the upload to reach the Galaxy job.

So:

Situation Do this
Failed before anything published Re-run the failed jobs, or fix and tag the next version
Published to PyPI, later job failed Re-run. skip-existing carries the PyPI job and the rest proceeds
Published everywhere, release is wrong Burn the version, tag the next one. Never re-tag
A job is stuck in waiting It needs a reviewer on the release environment (Step 3). This is a human action, not a stuck runner

If you add a publish step after publish-pypi, keep skip-existing and make the new step's failure recoverable the same way. An adopter with two indexes has two ways to half-publish and only one of them is reachable by re-running. kerbside does this for its two sequential packages.

That last row is worth knowing before debugging: a job awaiting deployment approval looks queued, and one v0.4.0 job sat in waiting for nine hours and forty minutes while it was mistaken for a runner shortage.

Verifying a Release

Tag Signature

gitsign verify --certificate-identity-regexp='.*' \
    --certificate-oidc-issuer='https://token.actions.githubusercontent.com' \
    v0.6.0

PyPI Attestation

Check the Provenance section on the package's PyPI page.

Artifact Attestation

cosign verify-attestation \
    --certificate-identity-regexp='.*' \
    --certificate-oidc-issuer='https://token.actions.githubusercontent.com' \
    package-0.6.0.tar.gz

📝 Report an issue with this page