Skip to main content

在 PyPI 中配置 OpenID Connect

在工作流中使用 OpenID Connect 来完成 PyPI 身份验证。

概述

借助 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 上的受信任发布者使用以下设置。

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

    • 所有者:myorg
    • 存储库名称:myproject
    • 工作流名称:release.yml
    • (可选)GitHub Actions 环境名称:release

更新 GitHub Actions 工作流程

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

注意****:在工作流或 OIDC 策略中使用环境时,建议将保护规则添加到环境中以提高安全性。 例如,可以在环境中配置部署规则,以限制可以部署到环境或访问环境机密的分支和标记。 有关详细信息,请参阅“使用环境进行部署”。

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

以下示例使用 pypa/gh-action-pypi-publish 操作来用 OIDC 令牌交换 PyPI API 令牌,然后使用后者将包的发布分发上传至 PyPI。

YAML
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 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@release/v1