gh action pypi publish
v1.12.2
Esta ação permite que você carregue seus pacotes de distribuição Python no diretório dist/ para PyPI. Este texto sugere uma visão geral minimalista do uso. Para instruções mais detalhadas, consulte o guia PyPA.
Se você tiver algum comentário sobre versões de ação específicas, deixe comentários nas discussões de anúncio correspondentes por lançamento.
master A versão do branch master foi desativada. Por favor, altere a versão do GitHub Action que você usa de master para release/v1 ou use uma tag exata, ou opte por usar um Git commit SHA completo e Dependabot.
Observação
No momento, a publicação confiável não pode ser usada em um fluxo de trabalho reutilizável. Em vez disso, é recomendável criar um fluxo de trabalho não reutilizável que contenha um trabalho que chame seu fluxo de trabalho reutilizável e, em seguida, executar a etapa de publicação confiável a partir de um trabalho separado nesse fluxo de trabalho não reutilizável. Como alternativa, você ainda pode usar um nome de usuário/token dentro do fluxo de trabalho reutilizável.
Observação
A publicação confiável às vezes é chamada de sua tecnologia subjacente – OpenID Connect ou, abreviadamente, OIDC. Se você vir referências à "publicação OIDC" no contexto do PyPI, é a isso que elas estão se referindo.
Este exemplo vai direto para as melhores práticas atuais. Se você quiser usar tokens de API diretamente ou um nome de usuário e senha menos seguros, veja como especificar nome de usuário e senha.
Esta ação oferece suporte à implementação de publicação confiável do PyPI, que permite a autenticação no PyPI sem um token de API configurado manualmente ou uma combinação de nome de usuário/senha. Para realizar uma publicação confiável com esta ação, o editor do seu projeto já deve estar configurado no PyPI.
Para entrar no fluxo de publicação confiável, configure o trabalho desta ação com o id-token: write e sem um nome de usuário ou senha explícitos:
# .github/workflows/ci-cd.ymljobs: pypi-publish:name: Carregar versão para PyPIruns-on: ubuntu-latestenvironment: nome: pypi url: https://pypi.org/p/<your-pypi-project -name>permissions: id-token: write # IMPORTANTE: esta permissão é obrigatória para publicações confiáveisetapas:# recupere suas distribuições aqui- name: Publique distribuições de pacotes em Usos do PyPI: pypa/gh-action-pypi-publish@release/v1
Observação
Dica profissional: em vez de usar ponteiros de ramificação, como unstable/v1 , fixe versões de Actions que você usa em versões marcadas ou identificadores de commit sha1. Isso tornará seus fluxos de trabalho mais seguros e reproduzíveis, evitando surpresas repentinas e desagradáveis.
Outros índices que suportam publicação confiável também podem ser usados, como TestPyPI:
- nome: Publicar distribuições de pacotes no TestPyPI usa: pypa/gh-action-pypi-publish@release/v1 com: url do repositório: https://test.pypi.org/legacy/
(não se esqueça de atualizar o nome do ambiente para testpypi ou similar!)
Observação
Dica profissional: defina apenas a permissão id-token: write no trabalho que publica, não globalmente. Além disso, tente separar a construção da publicação - isso garante que quaisquer scripts injetados maliciosamente no ambiente de construção ou teste não serão capazes de elevar privilégios enquanto passam despercebidos.
Um caso de uso comum é fazer upload de pacotes apenas em um commit marcado, para isso adicione um filtro ao trabalho:
if: github.event_name == 'push' &&startWith(github.ref, 'refs/tags')
Importante
O suporte para geração e upload de atestados digitais é atualmente experimental e limitado apenas a fluxos de publicação confiável usando PyPI ou TestPyPI. O suporte para esse recurso ainda não está estável; as configurações e o comportamento descritos abaixo podem mudar sem aviso prévio.
Observação
A geração e o upload de atestados digitais atualmente exigem autenticação com um editor confiável.
A geração de atestados digitais assinados para todos os arquivos de distribuição e o upload de todos eles agora estão ativados por padrão para todos os projetos que usam Publicação confiável. Para desativá-lo, defina attestations da seguinte forma:
com: atestados: falso
Os objetos de atestado são criados usando Sigstore para cada pacote de distribuição, assinando-os com a identidade fornecida pelo token OIDC do GitHub associado ao fluxo de trabalho atual. Isso significa que tanto a autenticação de publicação confiável quanto os atestados estão vinculados à mesma identidade.
Esta ação do GitHub não tem nada a ver com a construção de distribuições de pacotes . Os usuários são responsáveis por preparar dists para upload, colocando-os na pasta dist/ antes de executar esta ação.
Importante
Como esta ação do GitHub é baseada em docker, ela só pode ser usada em trabalhos baseados em GNU/Linux em fluxos de trabalho de CI/CD do GitHub Actions. Isso ocorre intencionalmente e é improvável que mude devido a uma série de considerações nas quais confiamos.
No entanto, isso não deve impedir a publicação de pacotes de distribuição específicos da plataforma. É altamente recomendável separar os trabalhos de construção de rodas específicas do sistema operacional do trabalho de publicação. Isso permite (1) testar exatamente os mesmos artefatos que estão prestes a ser carregados no PyPI, (2) evitar que trabalhos paralelos não sincronizados publiquem apenas parte dos dists de forma assíncrona (no caso de parte dos trabalhos falharem e outros terem sucesso, terminando com uma versão incompleta no PyPI) e (3) fazer um upload atômico para o PyPI (quando parte dos dists aparecer no PyPI, instaladores como o pip usarão essa versão para a resolução de dependências, mas isso pode fazer com que alguns ambientes usem sdists enquanto a roda para seu tempo de execução ainda não estiver disponível).
Para implementar esse tipo de orquestração, use actions/upload-artifact e actions/download-artifact para compartilhar os dists construídos entre estágios e trabalhos. Em seguida, use a configuração needs para ordenar os estágios de construção, teste e publicação.
Para obter melhores resultados, descubra que tipo de fluxo de trabalho atende às necessidades específicas do seu projeto.
Por exemplo, você pode implementar um trabalho paralelo que envie cada commit para TestPyPI ou para seu próprio servidor de indexação, como devpi . Para isso, você precisaria (1) especificar um valor repository-url personalizado e (2) gerar um número de versão exclusivo para cada upload para que não criassem conflitos. O último é possível se você usar o pacote setuptools_scm , mas você também pode inventar sua própria solução com base na distância até o último commit marcado.
Você precisará criar outro token para um host separado e salvá-lo como um segredo do repositório GitHub em um ambiente usado em seu trabalho. Porém, passar uma senha desabilitaria a publicação confiável sem segredo, então é melhor configurá-la ao publicar no TestPyPI e não em algo personalizado.
A invocação da ação neste caso seria semelhante a:
- nome: Publicar pacote no TestPyPI
usa: pypa/gh-action-pypi-publish@release/v1
com: senha: ${{ secrets.TEST_PYPI_API_TOKEN }}url do repositório: https://test.pypi.org/legacy/ Você pode alterar o diretório de destino padrão dist/ para qualquer diretório de sua preferência. A invocação da ação agora seria semelhante a:
- nome: Publicar pacote no PyPI usa: pypa/gh-action-pypi-publish@release/v1 com:packages-dir: custom-dir/
É recomendado que você execute twine check logo após produzir seus arquivos, mas isso também executa twine check antes do upload. Você também pode desativar a verificação do fio com:
com: verificar-metadados: falso
Às vezes, quando você publica versões de vários locais, seu fluxo de trabalho pode atingir condições de corrida. Por exemplo, ao publicar de vários CIs ou até mesmo ter fluxos de trabalho com as mesmas etapas acionadas no CI/CD do GitHub Actions para diferentes eventos relativos ao mesmo ato de alto nível.
Para facilitar este caso de uso, você pode usar a configuração skip-existing (desativada por padrão) da seguinte forma:
com: pular-existente: verdadeiro
Observação
Dica profissional: tente evitar ativar essa configuração sempre que possível. Se você tiver etapas para publicar em PyPI e TestPyPI, considere usá-lo apenas para o último, fazendo com que o primeiro falhe ruidosamente em duplicatas.
Às vezes, twine upload pode falhar e para depurar use a configuração verbose da seguinte maneira:
com: detalhado: verdadeiro
Você pode querer verificar se os arquivos no PyPI foram carregados automaticamente pelo script CI. Ele mostrará os valores SHA256, MD5, BLAKE2-256 dos arquivos a serem carregados.
com: print-hash: verdadeiro
O valor de nome de usuário padrão é __token__ . Se você publicar em um registro customizado que não fornece tokens de API, como devpi , talvez seja necessário especificar um par de nome de usuário e senha customizados. É assim que é feito.
com: usuário: guidopassword: ${{ secrets.DEVPI_PASSWORD }} O segredo usado em ${{ secrets.DEVPI_PASSWORD }} precisa ser criado na página do ambiente nas configurações do seu projeto no GitHub. Consulte Criando e usando segredos.
No passado, ao publicar no PyPI, a maneira mais segura de definir o escopo de acesso para publicação automática era usar o recurso de tokens de API do PyPI. Alguém poderia torná-lo no escopo do projeto e salvá-lo como um segredo vinculado ao ambiente nas configurações do repositório GitHub, nomeando-o ${{ secrets.PYPI_API_TOKEN }} , por exemplo. Consulte Criando e usando segredos. Embora ainda seja segura, a publicação confiável agora é incentivada em vez de tokens de API como uma prática recomendada em plataformas suportadas (como GitHub).
O Dockerfile e os scripts e documentação associados neste projeto são lançados sob a licença BSD de 3 cláusulas.
