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

教程：使用 CI/CD 自动构建和发布包

您可以使用 CI/CD 来构建和发布您的 PyPI 包。自动构建可以帮助您保持包的更新，并使其对他人可用。

在本教程中，您将创建一个新的 CI/CD 配置来构建、测试和发布一个示例 PyPI 包。完成后，您应该能更好地理解管道中每个步骤的工作原理，并能够将 CI/CD 集成到您自己的包注册表工作流程中。

要使用 CI/CD 自动构建和发布包：

  1. 创建 .gitlab-ci.yml 文件
    1. 可选。不使用 CI/CD 变量进行身份验证
  2. 检查管道

开始之前

在完成本教程之前，请确保您具备以下条件：

  • 一个测试项目。您可以使用任何您喜欢的 Python 项目，但建议为本次教程专门创建一个项目。
  • 熟悉 PyPI 和 GitLab 包注册表。

创建 .gitlab-ci.yml 文件

每个 CI/CD 配置都需要一个 .gitlab-ci.yml 文件。此文件定义了 CI/CD 管道中的每个阶段。在这种情况下，阶段包括：

  • build - 构建 PyPI 包。
  • test - 使用测试框架 pytest 验证包。
  • publish - 将包发布到包注册表。

要创建 .gitlab-ci.yml 文件：

  1. 在左侧边栏，选择 搜索或跳转至 并找到您的项目。

  2. 选择 代码 > 代码库。

  3. 在文件列表上方，选择您要提交到的分支。

  4. 选择 新建 ( plus ) 和 新建文件。

  5. 将文件命名为 .gitlab-ci.yml。在较大的窗口中，粘贴此示例配置：

    default:
  image: python:3.9
  cache:
    paths:
      - .pip-cache/
  before_script:
    - python --version
    - pip install --upgrade pip
    - pip install build twine

stages:
  - build
  - test
  - publish

variables:
  PIP_CACHE_DIR: "$CI_PROJECT_DIR/.pip-cache"

build:
  stage: build
  script:
    - python -m build
  artifacts:
    paths:
      - dist/

test:
  stage: test
  script:
    - pip install pytest
    - pip install dist/*.whl
    - pytest

publish:
  stage: publish
  script:
    - TWINE_PASSWORD=${CI_JOB_TOKEN} TWINE_USERNAME=gitlab-ci-token python -m twine upload --repository-url ${CI_API_V4_URL}/projects/${CI_PROJECT_ID}/packages/pypi dist/*
  rules:
    - if: $CI_COMMIT_TAG

  6. 选择 提交更改。

这里是我们提交的代码的简要说明：

  • image - 指定要使用的 Docker 镜像。
  • stages - 定义此管道的三个阶段。
  • variables 和 cache - 配置 PIP 使用缓存。这可以使后续管道运行得更快一些。
  • before_script - 安装完成三个阶段所需的工具。
  • build - 构建包并将结果存储为工件。
  • test - 安装并运行 pytest 来验证包。
  • publish - 使用 twine 将包上传到包注册表，仅在推送新标签时执行。 使用 CI_JOB_TOKEN 对包注册表进行身份验证。

不使用 CI/CD 变量进行身份验证

要对包注册表进行身份验证，示例配置使用了 CI_JOB_TOKEN，这是 GitLab CI/CD 自动提供的。 要发布到外部 PyPI 注册表，您必须在项目设置中配置一个秘密变量：

  1. 在左侧边栏，选择 设置 > CI/CD > 变量。

  2. 添加一个名为 PYPI_TOKEN 的新变量，将您的 PyPI API 令牌作为值。

  3. 在您的 .gitlab-ci.yml 文件中，将 publish:script 替换为：

    script:
- TWINE_PASSWORD=${PYPI_TOKEN} TWINE_USERNAME=__token__ python -m twine upload dist/*

检查管道

当您提交更改时，应该检查管道是否正确运行：

  • 在左侧边栏，选择 构建 > 管道。最近的管道应该包含我们之前定义的三个阶段。

如果管道尚未运行，请手动运行一个新管道并确保它成功完成。

最佳实践

为确保您的包的安全性和稳定性，您应该遵循向包注册表发布的最佳实践。 我们添加的配置：

  • 实现了缓存以加速您的管道。
  • 使用工件在阶段之间传递构建的包。
  • 包含一个测试阶段来在发布前验证包。
  • 使用 GitLab CI/CD 变量来处理敏感信息，如身份验证令牌。
  • 仅在推送新的 Git 标签时发布。这确保只发布正确版本化的发布。

恭喜！您已成功使用 GitLab CI/CD 构建了、测试并发布了一个包。您应该能够使用类似的配置来简化您自己的开发流程。