在 PyPI 中配置 OpenID Connect

概述

借助 OpenID Connect (OIDC)，GitHub Actions 工作流将可以使用 PyPI 完成身份验证，从而发布 Python 包。

本指南概述了如何将 PyPI 配置为信任 GitHub 的 OIDC，以作为联合标识，并演示了如何在 pypa/gh-action-pypi-publish 操作中使用此配置，将包发布到 PyPI（或其他 Python 包存储库），而无需进行任何手动 API 令牌管理。

先决条件

• 若要了解 GitHub 如何使用 OpenID Connect (OIDC) 及其体系结构和优势的基本概念，请参阅“关于使用 OpenID Connect 进行安全强化”。

• 在继续之前，必须规划安全策略，以确保仅以可预测的方式分配访问令牌。 要控制云提供商颁发访问令牌的方式，必须至少定义一个条件，以便不受信任的存储库无法为云资源请求访问令牌。 有关详细信息，请参阅“关于使用 OpenID Connect 进行安全强化”。

将标识提供者添加到 PyPI

要将 OIDC 与 PyPI 配合使用，请添加信任配置，以将 PyPI 上的每个项目关联到允许为其发布的每个存储库和工作流组合。

1. 登录 PyPI 并导航到要配置的项目的受信任发布设置。 对于名称为 myproject 的项目，这将位于 https://pypi.org/manage/project/myproject/settings/publishing/。

2. 配置 PyPI 项目与 GitHub 存储库（以及存储库内部的工作流）之间的信任关系。 例如，假设 GitHub 存储库位于 myorg/myproject 中，而发布工作流是在 release.yml 中定义的，并且使用 release 环境，则应为 PyPI 上的受信任发布者使用以下设置。

   Note

   输入这些值应当小心。 让不正确的用户、存储库或工作流能够发布到 PyPI 项目，等同于共享 API 令牌。

   • 所有者：myorg
   • 存储库名称：myproject
   • 工作流名称：release.yml
   • （可选）GitHub Actions 环境名称：release

更新 GitHub Actions 工作流程

在 PyPI 上注册受信任的发布者后，即可以更新发布工作流，以便使用受信任的发布。

pypa/gh-action-pypi-publish 操作提供了对受信任发布的内置支持，可通过向包含作业授予 id-token: write 权限，并且忽略 username 和 password，从而实现这种支持。

以下示例使用 pypa/gh-action-pypi-publish 操作来用 OIDC 令牌交换 PyPI API 令牌，然后使用后者将包的发布分发上传至 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