Configuring OpenID Connect in PyPI

Overview

OpenID Connect (OIDC) allows your GitHub Actions workflows to authenticate with PyPI to publish Python packages.

This guide gives an overview of how to configure PyPI to trust GitHub's OIDC as a federated identity, and demonstrates how to use this configuration in the pypa/gh-action-pypi-publish action to publish packages to PyPI (or other Python package repositories) without any manual API token management.

Prerequisites

• Informationen zu den grundlegenden Konzepten, nach denen GitHub OpenID Connect (OIDC) sowie die Architektur und Vorteile des Protokolls verwendet, findest du unter Informationen zur Sicherheitshärtung mit OpenID Connect.

• Bevor du fortfährst, musst du deine Sicherheitsstrategie planen, um sicherzustellen, dass Zugriffs-Token nur auf vorhersehbare Weise zugewiesen werden. Zur Steuerung, wie dein Cloud-Anbieter Zugriffs-Token ausgibt, musst du mindestens eine Bedingung definieren, damit nicht vertrauenswürdige Repositorys keine Zugriffs-Token für deine Cloud-Ressourcen anfordern können. Weitere Informationen finden Sie unter Informationen zur Sicherheitshärtung mit OpenID Connect.

• Beachte, dass du bestimmte Werte in der folgenden Dokumentation ersetzen musst, wenn du den Leitfaden auf GHE.com verwendest. Weitere Informationen findest du unter Informationen zur Sicherheitshärtung mit OpenID Connect.

Adding the identity provider to PyPI

To use OIDC with PyPI, add a trust configuration that links each project on PyPI to each repository and workflow combination that's allowed to publish for it.

1. Sign in to PyPI and navigate to the trusted publishing settings for the project you'd like to configure. For a project named myproject, this will be at http://pypi.org/manage/project/myproject/settings/publishing/.

2. Configure a trust relationship between the PyPI project and a GitHub repository (and workflow within the repository). For example, if your GitHub repository is at myorg/myproject and your release workflow is defined in release.yml with an environment of release, you should use the following settings for your trusted publisher on PyPI.

   Hinweis

   Enter these values carefully. Giving the incorrect user, repository, or workflow the ability to publish to your PyPI project is equivalent to sharing an API token.

   • Owner: myorg
   • Repository name: myproject
   • Workflow name: release.yml
   • (Optionally) a GitHub Actions environment name: release

Updating your GitHub Actions workflow

Once your trusted publisher is registered on PyPI, you can update your release workflow to use trusted publishing.

The pypa/gh-action-pypi-publish action has built-in support for trusted publishing, which can be enabled by giving its containing job the id-token: write permission and omitting username and password.

The following example uses the pypa/gh-action-pypi-publish action to exchange an OIDC token for a PyPI API token, which is then used to upload a package's release distributions to PyPI.

jobs:
  release-build:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-python@v5
        with:
          python-version: "3.x"

      - name: build release distributions
        run: |
          # NOTE: put your own distribution build steps here.
          python -m pip install build
          python -m build

      - name: upload windows dists
        uses: actions/upload-artifact@v4
        with:
          name: release-dists
          path: dist/

  pypi-publish:
    runs-on: ubuntu-latest
    needs:
      - release-build
    permissions:
      id-token: write

    steps:
      - name: Retrieve release distributions
        uses: actions/download-artifact@v4
        with:
          name: release-dists
          path: dist/

      - name: Publish release distributions to PyPI
        uses: pypa/gh-action-pypi-publish@3e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e2f

jobs:
  release-build:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-python@v5
        with:
          python-version: "3.x"

      - name: build release distributions
        run: |
          # NOTE: put your own distribution build steps here.
          python -m pip install build
          python -m build

      - name: upload windows dists
        uses: actions/upload-artifact@v4
        with:
          name: release-dists
          path: dist/

  pypi-publish:
    runs-on: ubuntu-latest
    needs:
      - release-build
    permissions:
      id-token: write

    steps:
      - name: Retrieve release distributions
        uses: actions/download-artifact@v4
        with:
          name: release-dists
          path: dist/

      - name: Publish release distributions to PyPI
        uses: pypa/gh-action-pypi-publish@3e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e2f