概述
借助 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 上的每个项目关联到允许为其发布的每个存储库和工作流组合。
-
登录 PyPI 并导航到要配置的项目的受信任发布设置。 对于名称为
myproject
的项目,这将位于https://pypi.org/manage/project/myproject/settings/publishing/
。 -
配置 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
权限,并且忽略 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