Skip to content

生成证明

PyPI 允许在上传时将证明附加到各个发布文件（发布版本中的源代码和二进制分发包）。

先决条件

在将证明文件上传至索引之前，请：

生成证明

最简单的方法

如果您使用pypa/gh-action-pypi-publish （官方 PyPA 操作）发布到 PyPI，默认情况下会自动生成并上传证明，无需额外配置。

手动方式

警告

注意！您可能不需要阅读此部分；它仅用于提供一些关于认证生成和上传的内部细节。如果您是普通用户，强烈建议您使用上述官方工作流程之一。

生成证明

重要的

手动生成认证并不能绕过 PyPI 目前对受支持的认证身份（即受信任的发布者）的限制。以下示例可用于使用受信任的发布者或 其他身份进行签名，但 PyPI 会在上传时拒绝非受信任发布者的认证。

使用pypi-attestations

pypi-attestations是一个便捷的库和命令行界面 (CLI)，用于生成和操作证明对象。您可以使用任一接口来生成证明。

例如，要为所有分布生成证明dist/：

python -m pip install pypi-attestations
python -m pypi_attestations sign dist/*

如果上述操作在启用了可信发布功能的 GitHub Actions 工作流中运行id-token: write （即，可信发布的普通上下文），它将使用调用它的 GitHub Actions 工作流的环境身份。

如果在本地运行，它会提示您执行 OAuth 流程以建立身份，并使用生成的身份。

有关作为 Python 库的使用方法，请参阅pypi-attestations 的文档。

从 Sigstore 捆绑包转换

证明在功能上（但不在结构上）与Sigstore 包兼容 ，这意味着任何可以生成 Sigstore 包的系统都可以进行调整以生成证明。

例如，GitHubactions/attest可以用于生成带有 PyPI发布证明标记的 Sigstore 包：

- name: attest
  uses: actions/attest@v1
  with:
    # Attest to every distribution
    subject-path: dist/*
    predicate-type: 'https://pypi.com.cn/attestations/publish/v1'
    predicate: '{}'

sigstore-python生成后，每个 Sigstore 包都可以在同一工作流程中或离线使用以下API 转换为等效的认证pypi-attestation：

from pypi_attestations import Attestation
from sigstore.models import Bundle

raw_bundle = "..."  # read the bundle's JSON
bundle = Bundle.from_json(raw_bundle)
attestation = Attestation.from_bundle(bundle)

print(attestation.model_dump_json())

上传证明文件

认证文件会作为正常文件上传流程的一部分上传到 PyPI。

如果您正在使用twine，可以通过向以下参数传递信息来上传任何相邻的证明及其关联--attestations文件twine upload：

twine upload --attestations dist/*

请参阅 PyPI 的旧版上传 API 文档，了解如何在上传 API 级别向文件上传添加证明。

首先，应该已经设置好使用可信发布进行上传的 GitLab 工作流。请参阅此处的说明。

一旦该工作流程建立起来，就可以通过在工作流程中添加一个在构建之后、发布之前运行的额外作业来生成证明：

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/"

整个工作流程，包括三个任务（构建、生成证明和发布），如下所示：

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:
      # Use "testpypi" if uploading to TestPyPI
      aud: pypi
  script:
    # Install dependencies
    - python -m pip install -U twine

    # Upload to PyPI using Trusted Publishing, including the generated attestations
    # Add "--repository testpypi" if uploading to TestPyPI
    - twine upload  --attestations python_pkg/dist/*

请注意，与可信发布工作流程相比，它有以下变化：

  • 新增了一项任务，用于generate-pypi-attestations生成证明并将其存储为工件。
  • 发布作业现在也依赖于generate-pypi-attestations，因为它需要从中下载生成的证明。
  • 发布作业现在会调用twine传递--attestations标志的函数，以启用证明上传。

pypi-attestations是一个便捷的库和命令行界面 (CLI)，用于生成和操作证明对象。您可以使用任一接口来生成证明。

例如，要为所有分布生成证明dist/：

python -m pip install pypi-attestations
python -m pypi_attestations sign dist/*

如果上述操作在具有工作负载标识的 Google Cloud 服务 （例如 Cloud Build、Compute Engine 等）中运行，则它将使用调用它的服务的环境标识。

有关作为 Python 库的使用方法，请参阅pypi-attestations 的文档。