Help us learn about your current experience with the documentation. Take the survey.

教程：使用 GitLab CI/CD 构建和签名 Python 包

本教程教你如何为 Python 包实现安全管道。该管道包含使用 GitLab CI/CD 和 Sigstore Cosign 对 Python 包进行加密签名和验证的阶段。

完成本教程后，你将学习如何：

使用 GitLab CI/CD 构建和签名 Python 包。
使用通用包注册表存储和管理包签名。
作为终端用户验证包签名。

包签名有什么好处？

包签名提供几个关键的安全优势：

真实性：用户可以验证包来自可信来源。
数据完整性：如果在分发过程中包被篡改，将被检测到。
不可否认性：可以加密证明包的来源。
供应链安全：包签名可以防止供应链攻击和受损的仓库。

开始之前

要完成本教程，你需要：

一个 GitLab 账户和测试项目。
对 Python 打包、GitLab CI/CD 和包注册表概念的基本熟悉。

步骤

以下是你要做的概述：

设置 Python 项目

首先，创建一个测试项目。在项目根目录中添加一个 pyproject.toml 文件：

[build-system]
requires = ["setuptools>=45", "wheel"]
build-backend = "setuptools.build_meta"

[project]
name = "<my_package>"  # 将被 CI/CD 管道动态替换
version = "<1.0.0>"    # 将被 CI/CD 管道动态替换
description = "<Your package description>"
readme = "README.md"
requires-python = ">=3.7"
authors = [
    {name = "<Your Name>", email = "<your.email@example.com>"},
]

[project.urls]
"Homepage" = "<https://gitlab.com/my_package>"  # 将被替换为实际项目 URL

确保将 Your Name 和 your.email@example.com 替换为你自己的个人信息。

当你完成以下步骤中的 CI/CD 管道构建时，管道会自动：

将 my_package 替换为项目名称的规范化版本。
将 version 更改为与管道版本匹配。
将 Homepage URL 更改为你的 GitLab 项目 URL。

添加基础配置

在你的项目根目录中，添加一个 .gitlab-ci.yml 文件。添加以下配置：

variables:
  # 所有作业的基础 Python 版本
  PYTHON_VERSION: '3.10'
  # 包名称和版本
  PACKAGE_NAME: ${CI_PROJECT_NAME}
  PACKAGE_VERSION: "1.0.0"  # 使用语义化版本
  # Sigstore 服务 URL
  FULCIO_URL: 'https://fulcio.sigstore.dev'
  REKOR_URL: 'https://rekor.sigstore.dev'
  # Sigstore 验证的标识
  CERTIFICATE_IDENTITY: 'https://gitlab.com/${CI_PROJECT_PATH}//.gitlab-ci.yml@refs/heads/${CI_DEFAULT_BRANCH}'
  CERTIFICATE_OIDC_ISSUER: 'https://gitlab.com'
  # 用于更快构建的 pip 缓存目录
  PIP_CACHE_DIR: "$CI_PROJECT_DIR/.pip-cache"
  # 自动接受 Cosign 的提示
  COSIGN_YES: "true"
  # 通用包注册表的基础 URL
  GENERIC_PACKAGE_BASE_URL: "${CI_API_V4_URL}/projects/${CI_PROJECT_ID}/packages/generic/${PACKAGE_NAME}/${PACKAGE_VERSION}"

default:
  before_script:
    # 在任何作业开始时规范化包名称一次
    - export NORMALIZED_NAME=$(echo "${CI_PROJECT_NAME}" | tr '-' '_')

# 基于 Python 的作业模板
.python-job:
  image: python:${PYTHON_VERSION}
  before_script:
    # 首先规范化包名称
    - export NORMALIZED_NAME=$(echo "${CI_PROJECT_NAME}" | tr '-' '_')
    # 然后安装 Python 依赖
    - pip install --upgrade pip
    - pip install build twine setuptools wheel
  cache:
    paths:
      - ${PIP_CACHE_DIR}

# Python + Cosign 作业模板
.python+cosign-job:
  extends: .python-job
  before_script:
    # 首先规范化包名称
    - export NORMALIZED_NAME=$(echo "${CI_PROJECT_NAME}" | tr '-' '_')
    # 然后安装依赖
    - apt-get update && apt-get install -y curl wget
    - wget -O cosign https://github.com/sigstore/cosign/releases/download/v2.2.3/cosign-linux-amd64
    - chmod +x cosign && mv cosign /usr/local/bin/
    - export COSIGN_EXPERIMENTAL=1
    - pip install --upgrade pip
    - pip install build twine setuptools wheel
stages:
  - build
  - sign
  - verify
  - publish
  - publish_signatures
  - consumer_verification

这个基础配置：

指示管道使用 Python 3.10 作为基础镜像以确保一致性
设置两个可重用模板：.python-job 用于基本 Python 操作，.python+cosign-job 用于签名操作
实现 pip 缓存以加速构建
通过将连字符转换为下划线来规范化包名称，以实现 Python 兼容性
在管道级别定义所有关键变量以便于管理