Publicando versões de distribuição de pacotes usando fluxos de trabalho de CI/CD do GitHub Actions

O CI/CD do GitHub Actions permite que você execute uma série de comandos sempre que ocorrer um evento na plataforma GitHub. Uma escolha popular é ter um fluxo de trabalho que é disparado por um evento push. Este guia mostra como publicar uma distribuição Python sempre que um commit marcado é enviado. Ele usará o GitHub Action pypa/gh-action-pypi-publish.

Atenção

Este guia presume que você já tem um projeto para o qual sabe como construir distribuições e ele reside no GitHub.

Salvando credenciais no GitHub

Neste guia, demonstraremos o envio para o PyPI e TestPyPI, o que significa que teremos dois conjuntos separados de credenciais. E precisaremos salvá-los nas configurações do repositório do GitHub.

Vamos começar! 🚀

  1. Vá para https://pypi.org/manage/account/#api-tokens e crie um novo token de API. Se você já tem o projeto no PyPI, limite o escopo do token apenas a esse projeto. Você pode chamá-lo de algo como GitHub Actions CI/CD — project-org/project-repo para que seja facilmente distinguível na lista de tokens. Não feche a página ainda – você não verá esse token novamente.

  2. Em uma guia ou janela separada do navegador, vá para a aba Configurações do seu repositório de destino e clique em Secrets na barra lateral esquerda.

  3. Crie um novo segredo chamado ` PYPI_API_TOKEN`` e copie e cole o token da primeira etapa.

  4. Agora, vá para https://test.pypi.org/manage/account/#api-tokens e repita as etapas. Salve esse token de TestePyPI no GitHub como TEST_PYPI_API_TOKEN.

    Atenção

    Se você não tiver uma conta TestPyPI, precisará criá-la. Não é o mesmo que uma conta do PyPI comum.

Criando uma definição de fluxo de trabalho

Os fluxos de trabalho de CI/CD do GitHub são declarados em arquivos YAML armazenados no diretório .github/workflows/ do seu repositório.

Vamos criar um arquivo chamado .github/workflows/publish-to-test-pypi.yml.

Comece com um nome significativo e defina o evento que deve fazer o GitHub executar este fluxo de trabalho:

name: Publish Python 🐍 distributions 📦 to PyPI and TestPyPI

on: push

Definindo um ambiente de tarefa do fluxo de trabalho

Agora, vamos adicionar a configuração inicial para nosso trabalho. É um processo que executará comandos que definiremos mais tarde. Neste guia, usaremos a versão estável mais recente do Ubuntu LTS fornecido pelo GitHub Actions:

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

Fazendo checkout do projeto e construindo as distribuições

Então, adicione o seguinte sob a seção build-n-publish:

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

Isso fará o download do seu repositório no executor de CI e, em seguida, instalará e ativará o Python 3.10.

E agora podemos construir dists a partir da fonte. Neste exemplo, usaremos o pacote build, presumindo que seu projeto tem um pyproject.toml configurado corretamente (veja PEP 517 /PEP 518).

Dica

Você pode usar qualquer outro método para construir distribuições, desde que produza artefatos prontos para enviar, salvos na pasta dist/.

Então, adicione isso à lista de etapas:

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

Publicando a distribuição para PyPI e TestPyPI

Finalmente, adicione as seguintes etapas ao final:

    - 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 }}

Essas duas etapas usam a GitHub Action pypa/gh-action-pypi-publish: a primeira carrega o conteúdo da pasta dist / para TestPyPI incondicionalmente e a segunda faz isso para PyPI, mas apenas se o commit atual estiver marcado.

Isso é tudo, pessoal!

Agora, sempre que você fizer um push de um commit com tag para seu repositório Git remoto no GitHub, este fluxo de trabalho irá publicá-lo no PyPI. E publicará qualquer push para TestPyPI que seja útil para fornecer construções de teste para seus usuários alfa, bem como garantir que sua versão pipeline permaneça saudável!