Publishing package distribution releases using GitHub Actions CI/CD workflows

GitHub Actions CI/CD allows you to run a series of commands whenever an event occurs on the GitHub platform. One popular choice is having a workflow that’s triggered by a push event. This guide shows you how to publish a Python distribution whenever a tagged commit is pushed. It will use the pypa/gh-action-pypi-publish GitHub Action.

注意

This guide assumes that you already have a project that you know how to build distributions for and it lives on GitHub.

Saving credentials on GitHub

In this guide, we’ll demonstrate uploading to both PyPI and TestPyPI, meaning that we’ll have two separate sets of credentials. And we’ll need to save them in the GitHub repository settings.

让我们开始吧！🚀

  1. 进入 https://pypi.org/manage/account/#api-tokens ，创建一个新的 API token 。如果您在 PyPI 上已经有了项目，那么请将令牌的范围限制在该项目上。您可以把它叫做 GitHub Actions CI/CD — project-org/project-repo，以便在 token 列表中容易区分。先不要关闭页面—您不会再次看到该标记。

  2. 在一个单独的浏览器标签或窗口中，进入你的目标存储库的 Settings 标签，然后点击左侧边栏的 Secrets 。

  3. 创建一个名为 PYPI_API_TOKEN 的新 secret ，并复制粘贴第一步中的令牌。

  4. Now, go to https://test.pypi.org/manage/account/#api-tokens and repeat the steps. Save that TestPyPI token on GitHub as TEST_PYPI_API_TOKEN.

    注意

    如果您没有 TestPyPI 账户，那么您就需要创建它。这和普通的 PyPI 账户不一样。

创建一个工作流定义

GitHub CI/CD工作流程是在 YAML 文件中声明的，它们存储在您仓库的 .github/workflows/ 目录下。

让我们创建一个 .github/workflows/publish-to-test-pypi.yml 文件。

用一个有意义的名字开始，并定义让 GitHub 运行这个工作流程的事件：

name: Publish Python 🐍 distributions 📦 to PyPI and TestPyPI

on: push

定义一个工作流程的工作环境

Now, let’s add initial setup for our job. It’s a process that will execute commands that we’ll define later. In this guide, we’ll use the latest stable Ubuntu LTS version provided by GitHub Actions:

jobs:
  build-n-publish:
    name: Build and publish Python 🐍 distributions 📦 to PyPI and TestPyPI
    runs-on: ubuntu-latest

Checking out the project and building distributions

然后，在 build-n-publish 部分添加以下内容：

    steps:
    - uses: actions/checkout@master
    - name: Set up Python 3.10
      uses: actions/setup-python@v3
      with:
        python-version: "3.10"

This will download your repository into the CI runner and then install and activate Python 3.10.

And now we can build dists from source. In this example, we’ll use build package, assuming that your project has a pyproject.toml properly set up (see PEP 517/PEP 518).

小技巧

You can use any other method for building distributions as long as it produces ready-to-upload artifacts saved into the dist/ folder.

因此，将此加入到步骤列表中：

    - name: Install pypa/build
      run: >-
        python -m
        pip install
        build
        --user
    - name: Build a binary wheel and a source tarball
      run: >-
        python -m
        build
        --sdist
        --wheel
        --outdir dist/
        .

在 PyPI 和 TestPyPI 上发布发行版

最后，在结尾添加以下步骤：

    - name: Publish distribution 📦 to Test PyPI
      uses: pypa/gh-action-pypi-publish@release/v1
      with:
        password: ${{ secrets.TEST_PYPI_API_TOKEN }}
        repository_url: https://test.pypi.org/legacy/
    - name: Publish distribution 📦 to PyPI
      if: startsWith(github.ref, 'refs/tags')
      uses: pypa/gh-action-pypi-publish@release/v1
      with:
        password: ${{ secrets.PYPI_API_TOKEN }}

These two steps use the pypa/gh-action-pypi-publish GitHub Action: the first one uploads contents of the dist/ folder into TestPyPI unconditionally and the second does that to PyPI, but only if the current commit is tagged.

就这些了，伙计们!

Now, whenever you push a tagged commit to your Git repository remote on GitHub, this workflow will publish it to PyPI. And it’ll publish any push to TestPyPI which is useful for providing test builds to your alpha users as well as making sure that your release pipeline remains healthy!