In this lesson, you will learn how to configure a GitHub Actions workflow to automatically build and publish your Python package to PyPI whenever you create a formal release tag in your repository.
The Role of Automation
Manually building wheels with build and uploading them via twine is prone to human error—you might forget to increment your version number or upload an outdated artifact. By using Continuous Integration (CI), you turn your distribution process into a repeatable, automated pipeline that triggers only when you are ready to ship.
Configuring the Workflow
GitHub Actions uses YAML files stored in .github/workflows/ to define these tasks. Since we are using modern standards like pyproject.toml and PEP 517 build backends, we can use the official pypa/gh-action-pypi-publish action. This action integrates seamlessly with PyPI’s "Trusted Publishers" mechanism, removing the need to store long-lived passwords in your repository settings.
Here is a simplified example of what that workflow configuration looks like:
name: Publish Package
on:
release:
types: [published]
jobs:
pypi-publish:
runs-on: ubuntu-latest
permissions:
id-token: write # Required for Trusted Publishers
steps:
- uses: actions/checkout@v4
- name: Set up Python
uses: actions/setup-python@v5
with:
python-version: '3.11'
- name: Install build tool
run: pip install build
- name: Build package
run: python -m build
- name: Publish to PyPI
uses: pypa/gh-action-pypi-publish@release/v1
How It Works
- Trigger: The workflow listens for the
releaseevent. When you create a new release on GitHub, the pipeline wakes up. - Environment: It spins up a clean, isolated environment to ensure the build is reproducible.
- Build: It runs
python -m build, which utilizes yourpyproject.tomlto create your source distribution and wheel. - Publish: The
gh-action-pypi-publishaction handles the authentication using an OIDC token and sends your artifacts to PyPI automatically.
This ensures that the exact code you "tagged" as a release is the exact code that gets distributed to users, maintaining a clean and professional release history.
Key Takeaway: Automating your upload process with CI ensures consistent, verifiable releases by removing manual build steps and leveraging secure authentication methods.