PyPI Trusted Publishing: OIDC‑Based, Tokenless Uploads for CI/CD

Why Trusted Publishing Matters

When a continuous‑integration pipeline pushes a new Python wheel to PyPI, it traditionally relies on a long‑lived API token or the project’s password stored in CI secrets. That token is a single point of failure: if the secret leaks, an attacker can upload malicious packages. PyPI’s Trusted Publishing feature replaces that static credential with an OIDC identity token, giving you a short‑lived upload token that lives only for the duration of the publish step.

What Trusted Publishing Is

Trusted Publishing is a permission model that lets a project delegate upload rights to an external OIDC provider (GitHub Actions, GitLab CI/CD, etc.). The publisher is scoped to a specific repository, workflow file, environment, and ref pattern. This scoping means that even if a workflow run is compromised, only the defined branches or tags can trigger an upload.

How the Flow Works

1. CI runs a workflow that needs to publish a package.
2. The workflow requests an OIDC token from the provider (e.g., GitHub).
3. PyPI validates the token against the publisher’s configuration and issues a short‑lived upload token.
4. The workflow uses that token to call twine upload (or similar) and pushes the wheel.
5. After the publish step completes, the upload token expires.

Setting Up a Trusted Publisher in PyPI

1. Navigate to the project’s Settings → Trusted publishing page on PyPI and click “Add trusted publisher.”

2. Choose the provider (e.g., GitHub). You’ll be prompted to provide a repository (e.g., org/repo), workflow (e.g., ci.yml), environment (e.g., production), and ref pattern (e.g., refs/tags/v*). These fields are mandatory; leaving any blank will result in a “publisher not found” error during upload.

3. Click “Create publisher.” PyPI records a JSON Web Token (JWT) claim set that your CI will later present. The publisher is now a “trusted” entity that can generate upload tokens.

Configuring GitHub Actions for Tokenless Uploads

Below is a minimal example of a GitHub Actions workflow that publishes a wheel without storing a PyPI token. The workflow relies on the pypa/gh-action-pypi-publish action, which automatically fetches an OIDC token and exchanges it for an upload token.

name: Publish
on:
  push:
    tags:
      - 'v*'
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Set up Python
        uses: actions/setup-python@v5
        with:
          python-version: '3.11'
      - name: Build wheel
        run: pip install build && python -m build
      - name: Publish to PyPI
        uses: pypa/gh-action-pypi-publish@v1.10.2
        with:
          # No token is provided; the action will use OIDC
          # Optionally, specify environment if configured
          # environment: production

Key points:

• Do not set password or username in the action. The action will request an OIDC token automatically.
• Ensure the workflow file name and ref pattern match the trusted publisher configuration on PyPI.
• Run the workflow on a protected branch or tag to avoid accidental publishes.

Verifying the Upload Was Authenticated via Trusted Publishing

1. After the workflow finishes, go to the project page and click “Release history.”
2. Open the newly created release and inspect the “Files” tab. The file hash should match the wheel built in the workflow.
3. In the project settings, open the “Trusted publishing” section and confirm that the publisher listed shows the workflow name and tag pattern you used.
4. Try a manual upload from your local machine without an OIDC flow; PyPI should reject it with a 401 error, confirming the publisher is not a blanket credential.

Trade‑offs and Limitations

• Scope is a double‑edged sword. Tight scoping reduces blast radius but can block legitimate releases if the ref pattern is too restrictive (e.g., only refs/tags/v* but you also want to publish from main).
• Trusted publishing does not make your project immutable. Once a file is uploaded for a given version, it cannot be overwritten or deleted. A malicious upload will still require bumping the version number.
• Not all CI providers support OIDC or the exact claim set required by PyPI. If your provider is missing a claim, the publisher will reject the token.
• Local development machines that lack OIDC support must still use traditional API tokens. This means you can’t fully eliminate static credentials unless every developer’s environment supports OIDC.
• Misconfigured publishers can block legitimate releases or, worse, allow uploads from untrusted forks if the ref pattern is too broad.

Actionable Checklist for Your Project

1. Add a trusted publisher in PyPI with the correct repository, workflow, environment, and ref pattern.
2. Update your CI workflow to use the provider’s OIDC token (no static token).
3. Test a publish from a protected tag to confirm the upload succeeds.
4. Verify that a local publish without an OIDC token fails.
5. Document the publisher settings in your project’s README so future maintainers understand the flow.

Adopting Trusted Publishing gives you a robust, short‑lived credential that tightens security without sacrificing the convenience of automated releases. Just remember: it’s a tool that replaces the token for the upload step, but it doesn’t change PyPI’s immutable release policy or eliminate all supply‑chain risks.