gh action pypi publish
v1.12.2
Cette action vous permet de télécharger vos packages de distribution Python dans le répertoire dist/ vers PyPI. Ce texte suggère un aperçu minimaliste de l'utilisation. Pour une procédure pas à pas plus détaillée, consultez le guide PyPA.
Si vous avez des commentaires concernant des versions d'action spécifiques, veuillez laisser des commentaires dans les discussions d'annonce par version correspondantes.
master La version de la branche master a été supprimée. Veuillez modifier la version de GitHub Action que vous utilisez de master à release/v1 ou utiliser une balise exacte, ou choisir d'utiliser un commit Git complet SHA et Dependabot.
Note
La publication approuvée ne peut pas être utilisée à partir d’un flux de travail réutilisable pour le moment. Il est recommandé de créer plutôt un flux de travail non réutilisable contenant une tâche appelant votre flux de travail réutilisable, puis d'effectuer l'étape de publication approuvée à partir d'une tâche distincte au sein de ce flux de travail non réutilisable. Alternativement, vous pouvez toujours utiliser un nom d'utilisateur/un jeton dans le flux de travail réutilisable.
Note
La publication approuvée est parfois désignée par sa technologie sous-jacente : OpenID Connect, ou OIDC en abrégé. Si vous voyez des références à la « publication OIDC » dans le contexte de PyPI, c'est à cela qu'elles font référence.
Cet exemple s'inscrit directement dans les meilleures pratiques actuelles. Si vous souhaitez utiliser des jetons API directement ou un nom d'utilisateur et un mot de passe moins sécurisés, découvrez comment spécifier le nom d'utilisateur et le mot de passe.
Cette action prend en charge l'implémentation de publication approuvée de PyPI, qui permet l'authentification auprès de PyPI sans jeton API configuré manuellement ni combinaison nom d'utilisateur/mot de passe. Pour effectuer une publication fiable avec cette action, l'éditeur de votre projet doit déjà être configuré sur PyPI.
Pour accéder au flux de publication approuvé, configurez la tâche de cette action avec l'autorisation id-token: write et sans nom d'utilisateur ou mot de passe explicite :
# .github/workflows/ci-cd.ymljobs : pypi-publish:name : Télécharger la version sur PyPIruns-on : ubuntu-latestenvironment : nom : pypi url : https://pypi.org/p/<your-pypi-project -name>permissions : id-token : write # IMPORTANT : cette autorisation est obligatoire pour les étapes de publication approuvées :# récupérez vos distributions ici- name : Publiez les distributions de packages sur PyPI utilise : pypa/gh-action-pypi-publish@release/v1
Note
Conseil de pro : au lieu d'utiliser des pointeurs de branche, comme unstable/v1 , épinglez les versions des actions que vous utilisez sur des versions étiquetées ou des identifiants de validation sha1. Cela rendra vos flux de travail plus sécurisés et mieux reproductibles, vous évitant ainsi des surprises soudaines et désagréables.
D'autres indices prenant en charge la publication fiable peuvent également être utilisés, comme TestPyPI :
- nom : publier les distributions de packages sur TestPyPI utilise : pypa/gh-action-pypi-publish@release/v1 avec : URL du référentiel : https://test.pypi.org/legacy/
(n'oubliez pas de mettre à jour le nom de l'environnement en testpypi ou similaire !)
Note
Conseil de pro : définissez uniquement l'autorisation id-token: write dans le travail qui effectue la publication, pas globalement. Essayez également de séparer la construction de la publication - cela garantit que tout script injecté de manière malveillante dans l'environnement de construction ou de test ne pourra pas élever les privilèges tout en passant inaperçu.
Un cas d'utilisation courant consiste à télécharger des packages uniquement sur un commit balisé, pour ce faire, ajoutez un filtre au travail :
si : github.event_name == 'push' && startWith(github.ref, 'refs/tags')
Important
La prise en charge de la génération et du téléchargement d'attestations numériques est actuellement expérimentale et limitée uniquement aux flux de publication de confiance utilisant PyPI ou TestPyPI. La prise en charge de cette fonctionnalité n'est pas encore stable ; les paramètres et le comportement décrits ci-dessous peuvent changer sans préavis.
Note
La génération et le téléchargement d'attestations numériques nécessitent actuellement une authentification auprès d'un éditeur de confiance.
La génération d'attestations numériques signées pour tous les fichiers de distribution et leur téléchargement ensemble sont désormais activés par défaut pour tous les projets utilisant Trusted Publishing. Pour le désactiver, définissez attestations comme suit :
avec : attestations : faux
Les objets d'attestation sont créés à l'aide de Sigstore pour chaque package de distribution, en les signant avec l'identité fournie par le jeton OIDC de GitHub associé au workflow actuel. Cela signifie que l'authentification de publication approuvée et les attestations sont liées à la même identité.
Cette action GitHub n'a rien à voir avec la création de distributions de packages . Les utilisateurs sont responsables de préparer les listes à télécharger en les plaçant dans le dossier dist/ avant d'exécuter cette action.
Important
Étant donné que cette action GitHub est basée sur Docker, elle ne peut être utilisée qu'à partir de tâches basées sur GNU/Linux dans les workflows CI/CD des actions GitHub. Ceci est intentionnel et il est peu probable que cela change en raison d'un certain nombre de considérations sur lesquelles nous nous appuyons.
Cela ne devrait cependant pas empêcher de publier des packages de distribution spécifiques à la plate-forme. Il est fortement conseillé de séparer les tâches de création des roues spécifiques au système d'exploitation de la tâche de publication. Cela permet de (1) tester exactement les mêmes artefacts qui sont sur le point d'être téléchargés sur PyPI, (2) d'empêcher les tâches parallèles non synchronisées de publier uniquement une partie des listes de manière asynchrone (au cas où une partie des tâches échouerait et que d'autres réussiraient). avec une version incomplète sur PyPI) et (3) effectuer un téléchargement atomique sur PyPI (lorsqu'une partie des listes apparaît sur PyPI, les installateurs comme pip utiliseront cette version pour la résolution des dépendances mais cela peut entraîner certains environnements utiliser des sdists alors que la roue pour leur exécution n'est pas encore disponible).
Pour implémenter ce type d'orchestration, veuillez utiliser actions/upload-artifact et actions/download-artifact actions pour partager les listes construites entre les étapes et les tâches. Ensuite, utilisez le paramètre needs pour ordonner les étapes de création, de test et de publication.
Pour de meilleurs résultats, déterminez quel type de flux de travail correspond aux besoins spécifiques de votre projet.
Par exemple, vous pouvez implémenter une tâche parallèle qui transmet chaque validation vers TestPyPI ou votre propre serveur d'index, comme devpi . Pour cela, vous devrez (1) spécifier une valeur repository-url personnalisée et (2) générer un numéro de version unique pour chaque téléchargement afin qu'ils ne créent pas de conflit. Ce dernier est possible si vous utilisez le package setuptools_scm mais vous pouvez également inventer votre propre solution en fonction de la distance jusqu'au dernier commit balisé.
Vous devrez créer un autre jeton pour un hôte distinct, puis l'enregistrer en tant que secret de dépôt GitHub dans un environnement utilisé dans votre travail. Cependant, transmettre un mot de passe désactiverait la publication sécurisée sans secret, il est donc préférable de le configurer à la place, lors de la publication sur TestPyPI et non sur quelque chose de personnalisé.
L’invocation de l’action dans ce cas ressemblerait à :
- nom : publier le package sur TestPyPI
utilise : pypa/gh-action-pypi-publish@release/v1
avec : mot de passe : ${{ secrets.TEST_PYPI_API_TOKEN }}url du référentiel : https://test.pypi.org/legacy/ Vous pouvez modifier le répertoire cible par défaut de dist/ par n'importe quel répertoire de votre choix. L’invocation de l’action ressemblerait désormais à :
- nom : Publier le package sur PyPI utilise : pypa/gh-action-pypi-publish@release/v1 avec: rép-packages : rép-personnalisé/
Il est recommandé d'exécuter twine check juste après avoir produit vos fichiers, mais cela exécute également twine check avant le téléchargement. Vous pouvez également désactiver le contrôle de ficelle avec :
avec : vérifier les métadonnées : false
Parfois, lorsque vous publiez des versions à partir de plusieurs endroits, votre flux de travail peut rencontrer des conditions de concurrence. Par exemple, lors de la publication à partir de plusieurs CI ou même lorsque des workflows avec les mêmes étapes sont déclenchés dans GitHub Actions CI/CD pour différents événements concernant le même acte de haut niveau.
Pour faciliter ce cas d'utilisation, vous pouvez utiliser le paramètre skip-existing (désactivé par défaut) comme suit :
avec : sauter-existant : vrai
Note
Conseil de pro : essayez d’éviter d’activer ce paramètre dans la mesure du possible. Si vous avez des étapes à suivre pour publier à la fois sur PyPI et TestPyPI, envisagez de l'utiliser uniquement pour ce dernier, car le premier échouera bruyamment sur les doublons.
Parfois, twine upload peut échouer et pour déboguer, utilisez le paramètre verbose comme suit :
avec : verbeux : vrai
Vous souhaiterez peut-être vérifier si les fichiers sur PyPI ont été automatiquement téléchargés par le script CI. Il affichera les valeurs SHA256, MD5, BLAKE2-256 des fichiers à télécharger.
avec : print-hash : vrai
La valeur du nom d'utilisateur par défaut est __token__ . Si vous publiez dans un registre personnalisé qui ne fournit pas de jetons API, comme devpi , vous devrez peut-être spécifier une paire nom d'utilisateur et mot de passe personnalisée. C'est comme ça que ça se passe.
avec : utilisateur : guidopassword : ${{ secrets.DEVPI_PASSWORD }} Le secret utilisé dans ${{ secrets.DEVPI_PASSWORD }} doit être créé sur la page d'environnement sous les paramètres de votre projet sur GitHub. Voir Création et utilisation de secrets.
Dans le passé, lors de la publication sur PyPI, le moyen le plus sécurisé de définir la portée de l'accès pour la publication automatique consistait à utiliser la fonctionnalité de jetons API de PyPI. On pourrait le rendre à l'échelle du projet et l'enregistrer en tant que secret lié à l'environnement dans les paramètres de son référentiel GitHub, en le nommant ${{ secrets.PYPI_API_TOKEN }} , par exemple. Voir Création et utilisation de secrets. Bien que toujours sécurisée, la publication fiable est désormais encouragée par rapport aux jetons API en tant que bonne pratique sur les plates-formes prises en charge (comme GitHub).
Le Dockerfile ainsi que les scripts et la documentation associés à ce projet sont publiés sous la licence BSD à 3 clauses.
