Skip to content
Tutorials Center
My learning

Topics

Lesson 31 of 38 ยท Testing and CI

Release Automation and Trusted Publishing

Automate Python package releases safely. Version bumps, changelogs, release checks, and publishing to PyPI from GitHub Actions with trusted publishing instead of tokens.

Releasing by hand is a ritual of typing commands in the right order and hoping you did not forget one: bump the version, update the changelog, build, check, upload. Each manual step is a chance for a mistake, and a copy of your PyPI token on a laptop is a security risk. A good release process is boring and automatic: you create a Git tag, and a workflow does the rest.

In this lesson you will learn how to choose version numbers, derive them from Git, generate a changelog, verify a release before publishing, and publish with trusted publishing, which lets PyPI trust your GitHub workflow directly, with no stored password. The upload itself happens on PyPI and GitHub, so those parts are read-only; the helper logic is runnable.

Choosing a versioning scheme

Two schemes dominate:

  • Semantic versioning (SemVer): MAJOR.MINOR.PATCH. Increase MAJOR for breaking changes, MINOR for new backward-compatible features, PATCH for bug fixes. Users can read risk from the number.
  • Calendar versioning (CalVer): 2025.3 or 25.3.1. The number tells you when, popular for tools with frequent releases and no strict compatibility promise.

Both are valid PEP 440 versions. Pick one, document it, and keep it. A small function can apply the bump rules consistently:

Python A version bump helper

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Single source of truth for the version

A version written in three places (pyproject.toml, __init__.py, the Git tag) will eventually disagree. Pick one source:

  1. Static in pyproject.toml: version = "1.4.2". Simplest; a release PR changes the line.
  2. From the Git tag with a plugin such as setuptools-scm or hatch-vcs: the tag v1.4.2 is the version, and untagged commits get development versions like 1.4.3.dev5+g1a2b3c4. Mark the field as dynamic:
TOML
[build-system]
requires = ["hatchling", "hatch-vcs"]
build-backend = "hatchling.build"

[project]
name = "myproject"
dynamic = ["version"]

[tool.hatch.version]
source = "vcs"
  1. Read at runtime from the installed metadata so the code never hard-codes it:
Python
from importlib.metadata import version
__version__ = version("myproject")

Changelogs

A changelog tells users what changed. Keep it for humans (the "Keep a Changelog" layout with Added, Changed, Fixed, Removed), or generate it from commit messages if your team follows a convention such as Conventional Commits (feat:, fix:, feat!: for breaking). Tools like towncrier, git-cliff and release-please automate this. The idea is easy to demonstrate:

Python Generate a changelog from commit messages

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Commits of type chore are deliberately left out: users do not care about them.

Pre-release checks

Before anything is uploaded, verify the files. A small gate in the release workflow catches the classic mistakes: tag and package version disagree, or an unexpected file is in dist/.

Python Check the tag against the built files

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

In a real pipeline you also run twine check dist/* (validates the long description renders), install the wheel into a clean environment and import it, and run the tests against it.

Trusted publishing

Historically you created a PyPI API token, pasted it into your CI secrets, and any leak (a log, a compromised dependency, a former teammate) allowed uploads. Trusted publishing replaces the long-lived secret with a short-lived identity check based on OpenID Connect (OIDC):

sequenceDiagram
    participant W as GitHub workflow
    participant G as GitHub OIDC
    participant P as PyPI
    W->>G: request identity token
    G-->>W: signed token (repo, workflow, environment)
    W->>P: upload dist/* with the token
    P->>P: does token match a configured trusted publisher?
    P-->>W: accepted (short-lived credential)

PyPI is told once which repository, workflow and environment may publish. Afterwards no secret exists to steal.

Setup on PyPI: open your project, Publishing, add a trusted publisher with your GitHub owner, repository, workflow file name and (recommended) environment name. For a project that does not exist yet, create a pending publisher.

The workflow:

YAML
name: Release

on:
  push:
    tags: ["v*"]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: astral-sh/setup-uv@v5
      - run: uv build
      - uses: actions/upload-artifact@v4
        with:
          name: dist
          path: dist/

  publish:
    needs: build
    runs-on: ubuntu-latest
    environment: pypi          # can require manual approval
    permissions:
      id-token: write          # needed for OIDC
    steps:
      - uses: actions/download-artifact@v4
        with:
          name: dist
          path: dist/
      - uses: pypa/gh-action-pypi-publish@release/v1

Notes on this design:

  • Building and publishing are separate jobs. Only the publish job has id-token: write, and it runs no project code, so a compromised test dependency cannot reach publishing rights.
  • The pypi environment in GitHub can require a reviewer's approval, adding a human gate before anything goes out.
  • To rehearse, repeat the setup with TestPyPI (repository-url: https://test.pypi.org/legacy/) and install from there. You do not need a rehearsal for every release, but do one the first time.
  • The publishing action can also create attestations that let users verify where a file was built.

A published file cannot be replaced: PyPI refuses to reuse a filename, even after you delete it. If a release is broken, yank it (it stays available for exact pins but is skipped by default) and publish a new version. Never rely on being able to "fix the same version".

Releasing end to end

  1. Merge finished work to main with CI green.
  2. Update the changelog (or let a bot open a release pull request).
  3. Create a tag: git tag v1.4.2 && git push origin v1.4.2 (or draft a GitHub release).
  4. The workflow builds, checks and publishes after approval.
  5. Verify: pip install myproject==1.4.2 in a clean environment, and announce the release.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What is the main advantage of trusted publishing over an API token?

    PyPI is configured to trust a specific repository, workflow and environment, and accepts short-lived credentials from it.
  2. 2. Which permission does the publish job need for trusted publishing on GitHub Actions?

    id-token: write lets the job request the OIDC token that PyPI verifies.
  3. 3. A release has a serious bug. What should you do on PyPI?

    Filenames can never be reused. Yanking hides the bad release from normal installs while a new version carries the fix.
  4. 4. Why is a conventional-commit feat!: message useful for automation?

    The exclamation mark signals a breaking change, so tools can suggest a major release and list it in the changelog.

Summary

  • Use SemVer or CalVer consistently, and keep one source of truth for the version (static, from Git tags, or read from metadata).
  • Maintain a changelog, by hand or generated from conventional commits.
  • Gate releases on checks: tag equals built version, twine check, a clean install and tests.
  • Publish from a tag-triggered workflow with trusted publishing (OIDC), separate build and publish jobs, and an approval environment.
  • Releases are permanent: fix with a new version, not by replacing files.

Next: Docker Images for Python Applications