第14章 使用受信任发布者发布
第14章:使用受信任发布者(Trusted Publisher)发布
一旦在 PyPI 上配置了受信任发布者(无论状态是"pending"还是"normal"),你就可以通过它在对应的平台上发布。下方的标签页分别描述各受支持受信任发布者的配置流程。
- GitHub Actions
- Google Cloud
- ActiveState
- GitLab CI/CD
简便方法
你可以使用 PyPA 提供的 pypi-publish action 来发布包。过程与普通发布几乎相同,区别在于你无需提供任何显式的用户名、密码或 API Token:GitHub 的 OIDC 身份提供商会自动处理所有事宜:
jobs:
pypi-publish:
name: upload release to PyPI
runs-on: ubuntu-latest
# 指定 GitHub 环境是可选的,但强烈建议这么做
environment: pypi
permissions:
# 重要:此权限对于受信任发布是强制要求的
id-token: write
steps:
# 在此处获取你的发行版
- name: Publish package distributions to PyPI
uses: pypa/gh-action-pypi-publish@release/v1
如果你正从基于密码或 API Token 的认证流程迁移过来,你的 diff 可能看起来像这样:
jobs:
pypi-publish:
name: upload release to PyPI
runs-on: ubuntu-latest
+ # 指定 GitHub 环境是可选的,但强烈建议这么做
+ environment: pypi
+ permissions:
+ # 重要:此权限对于受信任发布是强制要求的
+ id-token: write
steps:
# 在此处获取你的发行版
- name: Publish package distributions to PyPI
uses: pypa/gh-action-pypi-publish@release/v1
- with:
- username: __token__
- password: ${{ secrets.PYPI_TOKEN }}
请注意 id-token: write 权限:你必须在 Job 级别(强烈建议)或 Workflow 级别(不建议)提供此权限。如果没有它,发布 action 将没有足够的权限向 PyPI 进行身份验证。
强烈建议在 Job 级别使用此权限,以减少不必要的凭据暴露。
发布到 PyPI 以外的索引
PyPA 的 pypi-publish action 也支持在其他(非 PyPI)索引上进行受信任发布,前提是这些索引已启用受信任发布功能(且你已在上面配置了受信任发布者)。例如,你可以在 TestPyPI 上使用受信任发布:
- name: Publish package distributions to TestPyPI
uses: pypa/gh-action-pypi-publish@release/v1
with:
repository-url: https://test.pypi.org/legacy/
手动方法
警告:停下!你很可能不需要这个章节;它仅用于提供 GitHub Actions 和 PyPI 使用 OIDC 协调工作的内部细节。对于普通用户,强烈建议改用 PyPA 的
pypi-publishaction。
警告:下面描述的许多细节是特定于实现的,不属于标准化流程或兼容性保证范畴。它们不是公开接口的一部分,可能会随时更改。为了获得稳定的公开接口,你必须使用
pypi-publishaction。
使用 OIDC 发布者进行发布的流程如下:
- 从 OIDC 身份提供商获取 OIDC token;
- 将该 token 提交给 PyPI,PyPI 将返回一个短效期的 API key;
- 像往常一样使用该 API key(例如配合
twine使用)。
以下所有代码都假设运行在具有 id-token: write 权限的 GitHub Actions workflow runner 中。此权限至关重要;如果没有它,GitHub Actions 将拒绝提供 OIDC token。首先,让我们从 GitHub Actions 获取 OIDC token:
resp=$(curl -H "Authorization: bearer $ACTIONS_ID_TOKEN_REQUEST_TOKEN" \
"$ACTIONS_ID_TOKEN_REQUEST_URL&audience=pypi")
使用
audience=pypi仅适用于 PyPI。对于 TestPyPI,正确的 audience 是testpypi。更普遍地,你可以通过{index}/_/oidc/audience端点访问任何实例预期的 OIDC audience:
$ curl https://pypi.org/_/oidc/audience
{"audience":"pypi"}
响应将是一个 JSON 对象,其中包含 OIDC token。我们可以使用 jq 提取出来:
oidc_token=$(jq '.value' <<< "${resp}")
最后,我们可以将该 token 提交给 PyPI 并获取短效期 API token:
resp=$(curl -X POST https://pypi.org/_/oidc/mint-token -d "{\"token\": \"${oidc_token}\"}")
api_token=$(jq -r '.token' <<< "${resp}")
# 告知 GitHub Actions 在控制台日志中掩盖该 token,以避免泄露
echo "::add-mask::${api_token}"
此 API token 可以提供给 twine 或其他上传客户端:
TWINE_USERNAME=__token__ TWINE_PASSWORD=${api_token} twine upload dist/*
这一切可以整合到一个单一的 GitHub Actions workflow 中:
on:
release:
types:
- published
name: release
jobs:
pypi:
name: upload release to PyPI
runs-on: ubuntu-latest
permissions:
id-token: write
steps:
- uses: actions/checkout@v3
- uses: actions/setup-python@v4
with:
python-version: "3.x"
- name: deps
run: python -m pip install -U build
- name: build
run: python -m build
- name: mint API token
id: mint-token
run: |
# 获取环境中的 OIDC token
resp=$(curl -H "Authorization: bearer $ACTIONS_ID_TOKEN_REQUEST_TOKEN" \
"$ACTIONS_ID_TOKEN_REQUEST_URL&audience=pypi")
oidc_token=$(jq -r '.value' <<< "${resp}")
# 用 OIDC token 换取 API token
resp=$(curl -X POST https://pypi.org/_/oidc/mint-token -d "{\"token\": \"${oidc_token}\"}")
api_token=$(jq -r '.token' <<< "${resp}")
# 掩盖新生成的 API token,以免意外泄露
echo "::add-mask::${api_token}"
# 参考 workflow 中的下一步,查看如何使用此步骤输出
echo "api-token=${api_token}" >> "${GITHUB_OUTPUT}"
- name: publish
# gh-action-pypi-publish 会自动使用 TWINE_PASSWORD
uses: pypa/gh-action-pypi-publish@release/v1
with:
password: ${{ steps.mint-token.outputs.api-token }}
你可以使用 https://pypi.org/project/id/ 工具在 Google Cloud 服务上自动检测并生成 OIDC 凭据。首先,确保在你计划发布的安装环境中安装了 id 和 twine:
python -m pip install -U id twine
如果你不确定服务正在使用的服务账号邮箱是什么,可以这样验证:
python -m id pypi -d | jq 'select(.email) | .email'
在环境中生成 OIDC token 并存储。audience 应根据你发布的索引是 pypi 还是 testpypi:
oidc_token=$(python -m id pypi)
pypi仅适用于 PyPI。对于 TestPyPI,正确的 audience 是testpypi。更普遍地,你可以通过{index}/_/oidc/audience端点访问任何实例预期的 OIDC audience:
$ curl https://pypi.org/_/oidc/audience
{"audience":"pypi"}
最后,我们可以将该 token 提交给 PyPI 并获取短效期 API token:
resp=$(curl -X POST https://pypi.org/_/oidc/mint-token -d "{\"token\": \"${oidc_token}\"}")
api_token=$(jq -r '.token' <<< "${resp}")
这是 PyPI 的 URL。对于 TestPyPI,正确的域名应该是
test.pypi.org。
此 API token 可以提供给 twine 或其他上传客户端:
TWINE_USERNAME=__token__ TWINE_PASSWORD=${api_token} twine upload dist/*
ActiveState 平台作为零配置的 CI 解决方案,可自动为你的 PyPI 项目构建跨平台 wheel。一旦你在平台上完成设置并关联了你的 PyPI 项目,即可准备发布。关于 ActiveState 入门的更多信息,请参见此处。开始步骤如下:
- 将你的包发布到 ActiveState 目录。这将允许 ActiveState 平台为你构建它。
将上述代码块中的占位值替换为你的 ActiveState 组织名(通常为使用 State Tool CLI 运行以下命令: state publish \ --namespace private/ORGNAME \ --name PKG_NAME PKG_FILENAME \ --depend "builder/python-module-builder@>=0" \ --depend "language/python@>=3" \ --depend "language/python/setuptools@>=43.0.0" \ --depend "language/python/wheel@>=0"USERNAME-org,即ORGNAME)、包名(PKG_NAME)以及你的 sdist 或源 tarball 的文件名(PKG_FILENAME),然后运行该命令。记下输出中的TIMESTAMP。
命名空间必须以
private/开头,后跟你的组织名称。如果需要,你还可以追加额外的'文件夹'名称。
- 将包发布到 ActiveState 后,你需要创建一个构建脚本文件(
buildscript.as)来将其构建为 wheel 并发布到 PyPI。示例脚本如下。在你的activestate.yaml文件所在的同一文件夹中创建一个新的构建脚本文件,并命名为buildscript.as。粘贴以下代码,并将占位值替换为你项目中的对应值:你刚刚发布的包的时间戳(PUBLISHED_TIMESTAMP)、命名空间名称(即发布 ingredient 的文件夹,看起来类似private/USERNAME-org,即NAMESPACE)、包名(PKG_NAME)以及你要发布的版本(VERSION)。保存文件更改。at_time = "PUBLISHED_TIMESTAMP" publish_receipt = pypi_publisher( attempt=1, audience="testpypi", pypi_uri="test.pypi.org", src=wheels ) runtime = state_tool_artifacts(build_flags=[], src=sources) sources = solve( at_time=at_time, platforms=["7c998ec2-7491-4e75-be4d-8885800ef5f2"], requirements=[ Req(namespace="language", name="python", version=Eq(value="3.10.13")), Req(namespace="NAMESPACE", name="PKG_NAME", version=Eq(value="VERSION")), ], solver_version=null, ) wheel_srcs = select_ingredient(namespace="NAMESPACE", name="PKG_NAME", src=sources) wheels = make_wheel(at_time=at_time, python_version="3.10.13", src=wheel_srcs) main = runtime
然后,通过在终端中运行 state commit 将此构建脚本"提交"到系统中。现在你准备好发布到 PyPI 了!要将 wheel 发布到 PyPI,请运行:state eval publish_receipt。就这样!你已成功使用 ActiveState 平台发布了一个 Python wheel。
Buildscript 提示:
- 你可以留空
pypi_uri和audience字段,以直接发布到主 PyPI 仓库。- 如果遇到网络超时或其他瞬时错误,你可以增加
attempt参数以重试。platforms = [后面的字符串是你希望构建 wheel 的支持平台的 UUID。所有支持平台的列表可在此处找到。从提供的列表中选择所有适用于你项目的项。
如果你想发布前测试你的 wheel,请在运行
state eval publish_receipt之前执行以下步骤:
- 要单独构建你的 wheel,请运行
state eval wheels。- 构建 wheel 后,运行
state builds --all查看所有可用构建。记下你新 wheel 的HASH_ID。- 运行
state builds dl <HASH_ID>下载并测试你构建的 wheel。
这是一个示例 GitLab workflow,使用受信任发布将包构建并发布到 PyPI。与普通 workflow 的关键区别在于部署步骤(publish-job):
- 使用关键字
id_tokens向 GitLab 请求 OIDC token,名称为PYPI_ID_TOKEN,audience 为pypi。 - 调用
twine上传包时不指定 token。它将 OIDC token 发送给 PyPI 以换取 PyPI API token,然后使用该 API token 通过twine发布包。
build-job:
stage: build
image: python:3-bookworm
script:
- python -m pip install -U build
- cd python_pkg && python -m build
artifacts:
paths:
- "python_pkg/dist/"
publish-job:
stage: deploy
image: python:3-bookworm
dependencies:
- build-job
id_tokens:
# 如果上传到 TestPyPI,请使用 "TESTPYPI_ID_TOKEN"
PYPI_ID_TOKEN:
# 如果上传到 TestPyPI,请使用 "testpypi"
aud: pypi
script:
# 安装依赖
- python -m pip install -U twine
# 上传到 PyPI,如果上传到 TestPyPI,请添加 "--repository testpypi"
# 不指定 token 时,twine 将使用受信任发布
- twine upload python_pkg/dist/*