使用 GitLab CI/CD 自动构建与发布 PyPI 软件包

可以使用 CI/CD 构建和发布 PyPI 软件包。自动化构建有助于让软件包保持更新，并供其他人使用。

本教程将创建一份新的 CI/CD 配置，用来构建、测试和发布示例 PyPI 软件包。完成后，你将更清楚流水线中各步骤的工作方式，并能把 CI/CD 集成到自己的软件包仓库工作流中。

使用 CI/CD 自动构建和发布软件包的流程如下：

1. Create a .gitlab-ci.yml file
   1. 可选：在不使用 CI/CD 变量的情况下进行身份验证。
2. 查看流水线。

开始之前

完成本教程之前，请准备以下条件：

• 一个测试项目。可以使用任意 Python 项目，但建议专门为本教程创建一个项目。
• 熟悉 PyPI 和 GitLab 软件包仓库。

创建 .gitlab-ci.yml 文件

每份 CI/CD 配置都需要 .gitlab-ci.yml 文件，用来定义流水线的各个阶段。本例包含以下阶段：

• build：构建 PyPI 软件包。
• test：使用 pytest 测试框架验证软件包。
• publish：将软件包发布到软件包仓库。

创建 .gitlab-ci.yml 文件的步骤如下：

1. 在顶部栏选择“搜索或前往”（Search or go to），找到你的项目。

2. 在左侧栏选择“代码 → 仓库”（Code → Repository）。

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

4. 在右上角选择“新建”（Create new，加号）。

5. 将文件命名为 .gitlab-ci.yml，在较大的编辑区域粘贴以下示例配置：

   yaml

   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. 选择“提交更改”（Commit changes）。

下面简要说明刚提交的代码：

• image：指定使用的 Docker 镜像。
• stages：定义这条流水线的三个阶段。
• variables 和 cache：配置 PIP 使用缓存，使后续流水线运行更快。
• before_script：安装完成三个阶段所需的工具。
• build：构建软件包，并将结果保存为制品。
• test：安装并运行 pytest，验证软件包。
• publish：仅在推送新标签时，使用 twine 将软件包上传到仓库，并通过 CI_JOB_TOKEN 向软件包仓库进行身份验证。

在不使用 CI/CD 变量的情况下进行身份验证

示例配置使用 GitLab CI/CD 自动提供的 CI_JOB_TOKEN 向软件包仓库进行身份验证。若要发布到外部 PyPI 仓库，必须在项目设置中配置一个机密变量：

1. 在左侧栏选择“设置 → CI/CD → 变量”（Settings → CI/CD → Variables）。

2. 添加名为 PYPI_TOKEN 的变量，将你的 PyPI API 令牌作为其值。

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

   yaml

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

查看流水线

提交更改后，应查看流水线是否正确运行：

• 在左侧栏选择“构建 → 流水线”（Build → Pipelines）。最新流水线应包含前面定义的三个阶段。

如果流水线尚未运行，可以手动启动一条新流水线，并确认成功完成。

最佳实践

为保证软件包的安全性与稳定性，应遵循发布到软件包仓库的最佳实践。上面的配置：

• 使用缓存加快流水线。
• 通过制品在各阶段之间传递构建好的软件包。
• 在发布之前通过测试阶段验证软件包。
• 使用 GitLab CI/CD 变量保存身份验证令牌等敏感信息。
• 仅在推送新的 Git 标签时发布，确保只发布正确标记版本的发行版。

至此，已经完成通过 GitLab CI/CD 构建、测试和发布软件包的流程。可以采用类似配置，简化自己的开发工作流。