在 PyPI 中配置 OpenID Connect

概述

OpenID Connect (OIDC) 允许您的 GitHub Actions 工作流对 PyPI 进行身份验证以发布 Python 包。

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

先决条件

• 要了解 GitHub 如何使用 OpenID Connect (OIDC) 的基本概念及其架构和优势，请参阅“关于使用 OpenID Connect 加强安全性的信息”。

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

将身份提供者添加到 PyPI

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

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

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

   注意

   请仔细输入这些值。授予不正确的用户、存储库或工作流发布到您的 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