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

第19章 生成 PyPI 发布证明

生成证明 PyPI 允许在上传时将证明附加到单个发布文件(即发布包中的源码和二进制分发包)。

先决条件 在向索引上传证明之前,请先:

- 审阅 Linux Foundation 不可变记录通知,该通知适用于公共透明日志。 - 使用支持的 CI/CD 提供商设置 Trusted Publishing。下方列出了受支持的提供商及其配置说明。

注意 对其他 Trusted Publishers 的支持已在规划中。 更多详情请参见 #17001。

生成证明 GitHub Actions | GitLab CI/CD | Google Cloud

简易方法 如果通过 pypa/gh-action-pypi-publish 将包发布到 PyPI(该操作是 PyPA 官方 Action),默认情况下会自动生成并上传证明,无需额外配置。

手动方法

警告 请停下来。你可能不需要本节;其存在仅为提供关于证明生成和上传机制的内部细节。对于普通用户,强烈建议使用上述任一官方工作流。

生成证明

重要提示 手动生成证明并不能绕过 PyPI 当前对受支持证明身份(即 Trusted Publishers)的限制。以下示例可用于通过 Trusted Publisher 或其他身份进行签名,但 PyPI 会在上传时拒绝非 Trusted Publisher 的证明。

使用 pypi-attestations pypi-attestations 是一个用于生成和操作证明对象的便捷库及命令行工具。你可以使用任一接口来生成证明。 例如,要为 dist/ 目录中的所有分发包生成证明: ``` python -m pip install pypi-attestations python -m pypi_attestations sign dist/* ```

如果上述命令在启用了 `id-token: write` 的 GitHub Actions 工作流中运行(即 Trusted Publishing 的常规上下文),它将使用调用该工作流的 GitHub Actions 环境中的身份。 如果在本地运行,它会提示你执行 OAuth 流程以建立身份,并使用生成的身份。 关于作为 Python 库使用的说明,请参见 pypi-attestations 的文档。

从 Sigstore 包转换 证明在功能上(而非结构上)与 Sigstore 包兼容,这意味着任何能生成 Sigstore 包的系统都可以适配以生成证明。 例如,可以使用 GitHub 的 actions/attest 并指定 PyPI 发布证明标记来生成 Sigstore 包: ```yaml - name: attest uses: actions/attest@v1 with: # 证明所有分发包 subject-path: dist/* predicate-type: 'https://docs.pypi.org/attestations/publish/v1' predicate: '{}' ```

生成后,可以使用 sigstore-python 和 pypi-attestation 的 API 在同一工作流内或离线将每个 Sigstore 包转换为等效的证明: ```python from pypi_attestations import Attestation from sigstore.models import Bundle

raw_bundle = "..." # 读取包的 JSON 内容 bundle = Bundle.from_json(raw_bundle) attestation = Attestation.from_bundle(bundle)

print(attestation.model_dump_json()) ```

上传证明 证明是作为常规文件上传流程的一部分上传到 PyPI 的。 如果使用 twine,可以通过向 `twine upload` 传递 `--attestations` 参数,将相邻的证明与其关联文件一起上传: ``` twine upload --attestations dist/* ```

关于在上传 API 层级为文件上传添加证明,请参见 PyPI 的旧版上传 API 文档。

首先,需要已经设置好使用 Trusted Publishing 进行上传的 GitLab 工作流。配置说明请参见此处。 该工作流存在后,可以在工作流中添加一个额外任务来生成证明,该任务应在构建后、发布前运行: ```yaml generate-pypi-attestations: stage: build image: python:3-bookworm needs: - job: build-job artifacts: true id_tokens: SIGSTORE_ID_TOKEN: aud: sigstore script: - python -m pip install -U pypi-attestations - python -m pypi_attestations sign python_pkg/dist/* artifacts: paths: - "python_pkg/dist/" ```

包含三个任务(构建、生成证明、发布)的完整工作流如下所示: ```yaml 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/"

generate-pypi-attestations: stage: build image: python:3-bookworm needs: - job: build-job artifacts: true id_tokens: SIGSTORE_ID_TOKEN: aud: sigstore script: - python -m pip install -U pypi-attestations - python -m pypi_attestations sign python_pkg/dist/* artifacts: paths: - "python_pkg/dist/"

publish-job: stage: deploy image: python:3-bookworm dependencies: - build-job - generate-pypi-attestations id_tokens: PYPI_ID_TOKEN: # 如果上传到 TestPyPI,请使用 "testpypi" aud: pypi script: # 安装依赖项 - python -m pip install -U twine

# 使用 Trusted Publishing 上传到 PyPI,包括生成的证明 # 如果上传到 TestPyPI,请添加 "--repository testpypi" - twine upload --attestations python_pkg/dist/* ```

与 Trusted Publishing 工作流相比,主要变更如下:

- 新增了名为 generate-pypi-attestations 的任务,用于生成证明并将其存储为工件。 - 发布任务现在也依赖于 generate-pypi-attestations,因为它需要从该任务下载生成的证明。 - 发布任务现在调用 twine 时传递了 --attestations 标志,以启用证明上传。

pypi-attestations 是一个用于生成和操作证明对象的便捷库及命令行工具。你可以使用任一接口来生成证明。 例如,要为 dist/ 目录中的所有分发包生成证明: ``` python -m pip install pypi-attestations python -m pypi_attestations sign dist/* ```

如果上述命令在具有工作负载身份(如 Cloud Build、Compute Engine 等)的 Google Cloud 服务中运行,它将使用调用该服务的环境身份。 关于作为 Python 库使用的说明,请参见 pypi-attestations 的文档。

评论 (0)