进阶 docs.pypi.org 2026-10-20 06:39:13 · 24 阅读

第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-publish action。

警告:下面描述的许多细节是特定于实现的,不属于标准化流程或兼容性保证范畴。它们不是公开接口的一部分,可能会随时更改。为了获得稳定的公开接口,你必须使用 pypi-publish action。

使用 OIDC 发布者进行发布的流程如下:

  1. 从 OIDC 身份提供商获取 OIDC token;
  2. 将该 token 提交给 PyPI,PyPI 将返回一个短效期的 API key;
  3. 像往常一样使用该 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 入门的更多信息,请参见此处。开始步骤如下:

  1. 将你的包发布到 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"
      
    将上述代码块中的占位值替换为你的 ActiveState 组织名(通常为 USERNAME-org,即 ORGNAME)、包名(PKG_NAME)以及你的 sdist 或源 tarball 的文件名(PKG_FILENAME),然后运行该命令。记下输出中的 TIMESTAMP。

命名空间必须以 private/ 开头,后跟你的组织名称。如果需要,你还可以追加额外的'文件夹'名称。

  1. 将包发布到 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 之前执行以下步骤:

  1. 要单独构建你的 wheel,请运行 state eval wheels。
  2. 构建 wheel 后,运行 state builds --all 查看所有可用构建。记下你新 wheel 的 HASH_ID。
  3. 运行 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/*

评论 (0)