gh action pypi publish
v1.12.2
Esta acción le permite cargar sus paquetes de distribución de Python en el directorio dist/ a PyPI. Este texto sugiere una descripción general de uso minimalista. Para obtener un tutorial más detallado, consulte la guía de PyPA.
Si tiene algún comentario sobre versiones de acciones específicas, deje comentarios en las discusiones correspondientes al anuncio de lanzamiento.
master La versión de la rama master ya no existe. Por favor, cambie la versión de GitHub Action que usa de master a release/v1 o use una etiqueta exacta, u opte por usar un Git commit SHA y Dependabot completo.
Nota
La publicación confiable no se puede utilizar desde un flujo de trabajo reutilizable en este momento. En su lugar, se recomienda crear un flujo de trabajo no reutilizable que contenga un trabajo que llame a su flujo de trabajo reutilizable y luego realizar el paso de publicación confiable desde un trabajo separado dentro de ese flujo de trabajo no reutilizable. Alternativamente, aún puede usar un nombre de usuario/token dentro del flujo de trabajo reutilizable.
Nota
A veces se hace referencia a la publicación confiable por su tecnología subyacente: OpenID Connect u OIDC para abreviar. Si ve referencias a "publicación OIDC" en el contexto de PyPI, esto es a lo que se refieren.
Este ejemplo salta directamente a las mejores prácticas actuales. Si desea utilizar tokens API directamente o un nombre de usuario y contraseña menos seguros, consulte cómo especificar el nombre de usuario y la contraseña.
Esta acción admite la implementación de publicación confiable de PyPI, que permite la autenticación en PyPI sin un token API configurado manualmente o una combinación de nombre de usuario y contraseña. Para realizar una publicación confiable con esta acción, el editor de su proyecto ya debe estar configurado en PyPI.
Para ingresar al flujo de publicación confiable, configure el trabajo de esta acción con el id-token: write y sin un nombre de usuario o contraseña explícitos:
# .github/workflows/ci-cd.ymljobs: pypi-publish:name: cargar la versión en PyPIruns-on: ubuntu-latestenvironment: nombre: pypi url: https://pypi.org/p/<your-pypi-project -nombre>permisos: id-token: escribir # IMPORTANTE: este permiso es obligatorio para los pasos de publicación confiables:# recupere sus distribuciones aquí- nombre: Publicar paquete distribuciones para usos de PyPI: pypa/gh-action-pypi-publish@release/v1
Nota
Consejo profesional: en lugar de utilizar punteros de rama, como unstable/v1 , fije las versiones de las acciones que utiliza a las versiones etiquetadas o a los identificadores de confirmación sha1. Esto hará que sus flujos de trabajo sean más seguros y mejor reproducibles, evitando sorpresas repentinas y desagradables.
También se pueden utilizar otros índices que admitan publicaciones confiables, como TestPyPI:
- nombre: publicar distribuciones de paquetes en TestPyPI usos: pypa/gh-action-pypi-publish@release/v1 con: URL del repositorio: https://test.pypi.org/legacy/
(¡No olvide actualizar el nombre del entorno a testpypi o similar!)
Nota
Consejo profesional: configure solo el id-token: write en el trabajo que realiza la publicación, no globalmente. Además, intente separar la construcción de la publicación; esto garantiza que cualquier script inyectado maliciosamente en el entorno de construcción o prueba no pueda elevar los privilegios mientras pasa desapercibido.
Un caso de uso común es cargar paquetes solo en una confirmación etiquetada; para hacerlo, agregue un filtro al trabajo:
si: github.event_name == 'push' && comienza con (github.ref, 'refs/tags')
Importante
Actualmente, la compatibilidad con la generación y carga de certificaciones digitales es experimental y se limita solo a los flujos de Trusted Publishing que utilizan PyPI o TestPyPI. La compatibilidad con esta función aún no es estable; La configuración y el comportamiento que se describen a continuación pueden cambiar sin previo aviso.
Nota
Actualmente, generar y cargar certificaciones digitales requiere autenticación con un editor confiable.
La generación de certificaciones digitales firmadas para todos los archivos de distribución y la carga de todos juntos ahora está activada de forma predeterminada para todos los proyectos que utilizan Trusted Publishing. Para deshabilitarlo, configure attestations de la siguiente manera:
con: atestiguaciones: falsas
Los objetos de atestación se crean usando Sigstore para cada paquete de distribución, firmándolos con la identidad proporcionada por el token OIDC de GitHub asociado con el flujo de trabajo actual. Esto significa que tanto la autenticación de publicación confiable como las certificaciones están vinculadas a la misma identidad.
Esta acción de GitHub no tiene nada que ver con la creación de distribuciones de paquetes . Los usuarios son responsables de preparar los dists para cargarlos colocándolos en la carpeta dist/ antes de ejecutar esta acción.
Importante
Dado que esta GitHub Action está basada en Docker, solo se puede usar desde trabajos basados en GNU/Linux en flujos de trabajo CI/CD de GitHub Actions. Esto es así por diseño y es poco probable que cambie debido a una serie de consideraciones en las que confiamos.
Sin embargo, esto no debería impedir que uno publique paquetes de distribución específicos de la plataforma. Se recomienda encarecidamente separar los trabajos de creación de ruedas específicas del sistema operativo del trabajo de publicación. Esto permite (1) probar exactamente los mismos artefactos que están a punto de cargarse en PyPI, (2) evitar que los trabajos paralelos no sincronizados publiquen solo una parte de los dists de forma asíncrona (en caso de que parte de los trabajos fallen y otros tengan éxito y terminen). con una versión incompleta en PyPI) y (3) realizar una carga atómica a PyPI (cuando parte de los dists aparecen en PyPI, los instaladores como pip usarán esa versión para la resolución de dependencias, pero esto puede causar que algunos entornos usar sdists mientras la rueda para su tiempo de ejecución aún no esté disponible).
Para implementar este tipo de orquestación, utilice actions/upload-artifact y actions/download-artifact para compartir los dists creados entre etapas y trabajos. Luego, use la configuración needs para ordenar las etapas de compilación, prueba y publicación.
Para obtener mejores resultados, averigüe qué tipo de flujo de trabajo se adapta a las necesidades específicas de su proyecto.
Por ejemplo, podría implementar un trabajo paralelo que envíe cada confirmación a TestPyPI o a su propio servidor de índice, como devpi . Para esto, necesitaría (1) especificar un valor repository-url personalizado y (2) generar un número de versión único para cada carga para que no creen un conflicto. Esto último es posible si usa el paquete setuptools_scm , pero también puede inventar su propia solución en función de la distancia hasta la última confirmación etiquetada.
Deberá crear otro token para un host independiente y luego guardarlo como secreto de repositorio de GitHub en un entorno utilizado en su trabajo. Sin embargo, pasar una contraseña deshabilitaría la publicación confiable y sin secretos, por lo que es mejor configurarla al publicar en TestPyPI y no en algo personalizado.
La invocación de la acción en este caso sería así:
- nombre: publicar paquete en TestPyPI
usos: pypa/gh-action-pypi-publish@release/v1
con:contraseña: ${{ secrets.TEST_PYPI_API_TOKEN }}url-repositorio: https://test.pypi.org/legacy/ Puede cambiar el directorio de destino predeterminado de dist/ a cualquier directorio de su agrado. La invocación de la acción ahora se vería así:
- nombre: publicar paquete en PyPI usos: pypa/gh-action-pypi-publish@release/v1 con:directorio-paquetes:directorio-personalizado/
Se recomienda ejecutar twine check justo después de producir los archivos, pero esto también ejecuta twine check antes de cargarlos. También puedes desactivar el control del hilo con:
con: verificar-metadatos: falso
A veces, cuando publica lanzamientos desde varios lugares, su flujo de trabajo puede verse afectado por condiciones de carrera. Por ejemplo, cuando se publica desde múltiples CI o incluso cuando se activan flujos de trabajo con los mismos pasos dentro de GitHub Actions CI/CD para diferentes eventos relacionados con el mismo acto de alto nivel.
Para facilitar este caso de uso, puede utilizar la configuración skip-existing (deshabilitada de forma predeterminada) de la siguiente manera:
con: omitir-existente: verdadero
Nota
Consejo profesional: intente evitar habilitar esta configuración siempre que sea posible. Si tiene pasos para publicar tanto en PyPI como en TestPyPI, considere usarlo solo para este último, ya que el primero fallará estrepitosamente en los duplicados.
A veces, twine upload puede fallar y, para depurar, utilice la configuración verbose de la siguiente manera:
con: detallado: verdadero
Es posible que desee verificar si los archivos en PyPI se cargaron automáticamente mediante un script CI. Mostrará los valores SHA256, MD5, BLAKE2-256 de los archivos que se cargarán.
con:print-hash: verdadero
El valor de nombre de usuario predeterminado es __token__ . Si publica en un registro personalizado que no proporciona tokens API, como devpi , es posible que deba especificar un par de nombre de usuario y contraseña personalizado. Así es como se hace.
con:usuario: guidocontraseña: ${{ secretos.DEVPI_PASSWORD }} El secreto utilizado en ${{ secrets.DEVPI_PASSWORD }} debe crearse en la página del entorno en la configuración de su proyecto en GitHub. Consulte Creación y uso de secretos.
En el pasado, al publicar en PyPI, la forma más segura de determinar el alcance del acceso para la publicación automática era utilizar la función de tokens API de PyPI. Se podría hacer que tenga un alcance de proyecto y guardarlo como un secreto vinculado al entorno en la configuración de su repositorio de GitHub, nombrándolo ${{ secrets.PYPI_API_TOKEN }} , por ejemplo. Consulte Creación y uso de secretos. Si bien sigue siendo segura, ahora se recomienda la publicación confiable a través de tokens API como práctica recomendada en plataformas compatibles (como GitHub).
El Dockerfile y los scripts y la documentación asociados en este proyecto se publican bajo la licencia BSD de 3 cláusulas.
