Konfigurieren von OpenID Connect in PyPI

Verwenden Sie OpenID Connect in Ihren Workflows zum Authentifizieren bei PyPI.

In diesem Artikel

Übersicht

Mit OpenID Connect (OIDC) können Sie Ihre GitHub Actions-Workflows mit PyPI authentifizieren, um Python-Pakete zu veröffentlichen.

Diese Anleitung gibt einen Überblick darüber, wie PyPI so konfiguriert wird, dass es dem OIDC von GitHub als Verbundidentität vertraut, und demonstriert, wie diese Konfiguration in der pypa/gh-action-pypi-publish-Aktion verwendet werden kann, um Pakete in PyPI (oder anderen Python-Paket-Repositories) zu veröffentlichen, ohne dass ein manuelles API-Token-Management erforderlich ist.

Voraussetzungen

  • Informationen zu den grundlegenden Konzepten, nach denen GitHub OpenID Connect (OIDC) sowie die Architektur und Vorteile des Protokolls verwendet, findest du unter 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 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 OpenID Connect.

Hinzufügen des Identitätsanbieters zu PyPI

Um OIDC mit PyPI zu verwenden, fügen Sie eine Vertrauenskonfiguration hinzu, die jedes Projekt auf PyPI mit jeder Repository- und Workflowkombination verknüpft, die dafür veröffentlicht werden darf.

  1. Melden Sie sich bei PyPI an und navigieren Sie zu den vertrauenswürdigen Veröffentlichungseinstellungen für das Projekt, das Sie konfigurieren möchten. Für ein Projekt mit dem Namen myproject ist das bei https://pypi.org/manage/project/myproject/settings/publishing/.

  2. Konfigurieren Sie eine Vertrauensstellung zwischen dem PyPI-Projekt und einem GitHub-Repository (und einem Workflow innerhalb des Repositorys). Wenn Ihr GitHub-Repository z. B. bei myorg/myproject ist und ihr Veröffentlichungsworkflow in release.yml in einer Umgebung von release definiert ist, sollten Sie die folgenden Einstellungen für Ihren vertrauenswürdigen Herausgeber in PyPI verwenden.

    Hinweis

    Gib diese Werte sorgfältig ein. Wenn Sie dem falschen Benutzer, Repository oder Workflow die Möglichkeit zum Veröffentlichen in Ihrem PyPI-Projekt geben, ist das gleichbedeutend mit der Freigabe eines API-Tokens.

    • Besitzer: myorg
    • Repository-Name: myproject
    • Workflowname: release.yml
    • (Optional) ein GitHub Actions-Umgebungsname: release

Aktualisieren deines GitHub Actions-Workflows

Sobald Ihr vertrauenswürdiger Herausgeber auf PyPI registriert ist, können Sie Ihren Freigabe-Workflow so aktualisieren, dass vertrauenswürdige Veröffentlichungen verwendet werden.

Hinweis

Wenn Umgebungen in Workflows oder in OIDC-Richtlinien verwendet werden, wird empfohlen, der Umgebung Schutzregeln für zusätzliche Sicherheit hinzuzufügen. Du kannst z. B. Bereitstellungsregeln für eine Umgebung konfigurieren, um einzuschränken, welche Verzweigungen und Tags in der Umgebung oder in geheimen Umgebungsschlüsseln bereitgestellt werden können. Weitere Informationen finden Sie unter Verwalten von Umgebungen für die Bereitstellung.

Die pypa/gh-action-pypi-publish-Aktion verfügt über integrierte Unterstützung für die vertrauenswürdige Veröffentlichung, die aktiviert werden kann, indem dem enthaltenden Auftrag die id-token: write-Berechtigung erteilt wird und username und password weggelassen werden.

Im folgenden Beispiel wird die pypa/gh-action-pypi-publish-Aktion verwendet, um ein OIDC-Token gegen ein PyPI-API-Token auszutauschen, das dann zum Hochladen der Freigabeverteilungen eines Pakets in PyPI verwendet wird.

YAML
# Dieser Workflow verwendet Aktionen, die nicht von GitHub zertifiziert sind.
# Sie werden von einem Drittanbieter bereitgestellt und unterliegen
# separaten Nutzungsbedingungen, Datenschutzbestimmungen und Support
# Onlinedokumentation.
jobs:
  release-build:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v5

      - 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@v5
        with:
          name: release-dists
          path: dist/

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