Configurando o OpenID Connect no PyPI

Use o OpenID Connect em seus fluxos de trabalho para se autenticar no PyPI.

Neste artigo

Visão geral

O OpenID Connect (OIDC) permite que seus fluxos de trabalho do GitHub Actions se autentiquem com o PyPI para publicar pacotes do Python.

Esse guia fornece uma visão geral de como configurar o PyPI para confiar no OIDC do GitHub como uma identidade federada e demonstra como usar essa configuração na ação pypa/gh-action-pypi-publish para publicar pacotes no PyPI (ou em outros repositórios de pacotes Python) sem nenhum gerenciamento manual de token de API.

Pré-requisitos

  • Para saber os conceitos básicos de como o GitHub usa o OIDC (OpenID Connect), além da arquitetura e dos benefícios, confira "Sobre o enrijecimento de segurança com o OpenID Connect".

  • Antes de prosseguir, você deve planejar sua estratégia de segurança para garantir que os tokens de acesso sejam atribuídos apenas de forma previsível. Para controlar como o provedor de nuvem emite os tokens de acesso, você precisa definir, pelo menos, uma condição, para que os repositórios não confiáveis não possam solicitar tokens de acesso aos seus recursos de nuvem. Para obter mais informações, confira "Sobre o enrijecimento de segurança com o OpenID Connect".

  • Se você estiver seguindo este guia sobre o GHE.com, entenda que você precisa substituir alguns valores na documentação a seguir. Confira "Sobre o enrijecimento de segurança com o OpenID Connect".

Adicionando o provedor de identidade ao PyPI

Para usar o OIDC com o PyPI, adicione uma configuração de confiança que vincule cada projeto no PyPI a cada repositório e combinação de fluxo de trabalho que tenha permissão para publicar para ele.

  1. Faça login no PyPI e navegue até as configurações de publicação confiáveis do projeto que você deseja configurar. Para um projeto chamado myproject, isso será feito em https://pypi.org/manage/project/myproject/settings/publishing/.

  2. Configure uma relação de confiança entre o projeto PyPI e um repositório do GitHub (e o fluxo de trabalho dentro desse repositório). Por exemplo, se o seu repositório do GitHub estiver em myorg/myproject e o seu fluxo de trabalho de lançamento estiver definido em release.yml com um ambiente de release, você deverá usar as seguintes configurações para o seu editor confiável no PyPI.

    Observação: digite esses valores com cuidado. Dar ao usuário, repositório ou fluxo de trabalho incorreto a capacidade de publicar no seu projeto PyPI é equivalente a compartilhar um token de API.

    • Proprietário: myorg
    • Nome do repositório: myproject
    • Nome do fluxo de trabalho: release.yml
    • (Opcionalmente) um nome de ambiente do GitHub Actions: release

Atualizar o seu fluxo de trabalho de GitHub Actions

Depois que seu editor confiável estiver registrado no PyPI, você poderá atualizar seu fluxo de trabalho de lançamento para usar a publicação confiável.

Observação: quando os ambientes são usados em fluxos de trabalho ou em políticas OIDC, recomendamos adicionar regras de proteção ao ambiente para segurança adicional. Por exemplo, você pode configurar regras de implantação em um ambiente para restringir quais ramificações e tags podem ser implantadas no ambiente ou acessar segredos de ambiente. Para obter mais informações, confira "Gerenciar ambientes para implantação".

A ação pypa/gh-action-pypi-publish tem suporte integrado para publicação confiável, que pode ser ativado dando ao trabalho que o contém a permissão id-token: write e omitindo username e password.

O exemplo a seguir usa a ação pypa/gh-action-pypi-publish para trocar um token OIDC por um token da API do PyPI, que é então usado para carregar as distribuições de lançamento de um pacote no PyPI.

YAML
jobs:
  release-build:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-python@v5
        with:
          python-version: "3.x"

      - name: build release distributions
        run: |
          # NOTE: put your own distribution build steps here.
          python -m pip install build
          python -m build

      - name: upload windows dists
        uses: actions/upload-artifact@v4
        with:
          name: release-dists
          path: dist/

  pypi-publish:
    runs-on: ubuntu-latest
    needs:
      - release-build
    permissions:
      id-token: write

    steps:
      - name: Retrieve release distributions
        uses: actions/download-artifact@v4
        with:
          name: release-dists
          path: dist/

      - name: Publish release distributions to PyPI
        uses: pypa/gh-action-pypi-publish@3e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e2f