Publier une action GitHub personnalisée

Effectué

Ici, vous allez découvrir comment choisir la bonne visibilité pour votre action, les bonnes pratiques pour la documentation et le versioning de votre action, et comment publier votre action sur GitHub Marketplace.

Choisir un emplacement pour votre action

Lors de la création d’une action, il est important de d’abord décider où vous voulez que cette action se produise et quelle doit être la visibilité de cette action, si elle sera public ou private. La visibilité de l’action va déterminer les recommandations et les exigences nécessaires pour publier cette action. Examinons plus en détail ces deux options de visibilité.

Public

Les workflows de n’importe quel dépôt peuvent utiliser des actions publiques. Si vous développez une action avec l’intention de la rendre open source ou disponible publiquement sur GitHub Marketplace, nous recommandons (et c’est même impératif dans la plupart des cas) que l’action ait son propre dépôt au lieu de la regrouper avec une autre partie du code de l’application. Ceci vous permet de gérer les versions, de faire le suivi et de publier l’action comme n’importe quel autre élément du logiciel. Cela permet à la communauté GitHub de découvrir plus facilement l’action, de limiter l’étendue du code base pour les développeurs qui corrigent les problèmes et étendent l’action, et sépare le versioning de l’action du versioning du reste du code de l’application.

Privées

Quand une action se trouve dans un dépôt privé, seuls les workflows du même dépôt peuvent l’utiliser. Avec les actions privées, vous pouvez stocker les fichiers de l’action à n’importe quel emplacement de votre dépôt. Si vous prévoyez de combiner le code des actions, des workflows et de l’application dans un même dépôt, nous recommandons de stocker l’action dans le répertoire .github. Par exemple, .github/actions/action-a et .github/actions/action-b.

Documenter votre action

Il peut être très frustrant d’utiliser un nouvel outil ou une nouvelle application quand la documentation est vague ou même manquante. Il est important d’inclure une bonne documentation avec votre action afin que d’autres personnes puissent voir comment elle fonctionne, que vous envisagiez de la rendre publique ou privée. La première chose à faire est de créer un fichier README.md pour votre action.

Le fichier README.md est souvent le premier endroit où les développeurs vont regarder pour voir comment l’action fonctionne. C’est un bon endroit pour inclure toutes les informations importantes relatives à l’action. Voici une liste non exhaustive des éléments à inclure :

• Une description détaillée de ce que fait l’action
• Les arguments d’entrée et de sortie obligatoires
• Les arguments d’entrée et de sortie facultatifs
• Les secrets utilisés par l’action
• Les variables d’environnement utilisées par l’action
• Un exemple d’utilisation de votre action dans un workflow

En règle générale, le fichier README.md doit inclure tout ce qu’un utilisateur doit savoir pour utiliser l’action. Si vous pensez qu’il peut s’agir d’informations utiles, incluez-les dans le fichier README.md.

Publier et gérer les versions de votre action

Si vous développez une action que d’autres personnes vont utiliser, qu’elle soit publique ou privée, vous devez définir une stratégie de gestion des publications pour contrôler la façon dont les mises à jour sont distribuées. Les mises à jour de version majeures, y compris les correctifs critiques nécessaires et les correctifs de sécurité qui affectent la compatibilité, doivent être documentées clairement.

Bonnes pratiques pour la gestion des publications et des versions

Une bonne stratégie de gestion des publications doit inclure des recommandations sur le versioning. Les utilisateurs ne doivent pas référencer la branche par défaut d’une action avec l’action, car la branche par défaut est susceptible de contenir le code le plus récent (qui peut ou non être stable), ce qui peut aboutir à l’interruption du workflow. Au lieu de cela, nous recommandons que les utilisateurs spécifient une version majeure lors de l’utilisation de l’action et de les diriger vers une version plus spécifique s’ils rencontrent des problèmes. Pour cela, ils doivent configurer leur workflow GitHub Actions pour qu’il cible une étiquette, le SHA d’un commit ou une branche spécifique nommée pour une publication. Examinons plus en détail ces options de publication.

Balises

Les étiquettes peuvent être un bon moyen de gérer les publications d’une action. En utilisant des étiquettes, les utilisateurs peuvent facilement distinguer entre les versions majeures et les versions mineures. Voici une liste de pratiques utiles à considérer lors de la création de publications :

• Créez et validez une publication sur une branche de publication (comme release/v1) avant de créer l’étiquette de publication (par exemple v1.0.2).
• Utilisez un versioning sémantique.
• Déplacez l’étiquette de version majeure (par exemple v1, v2) pour qu’elle pointe vers la référence Git de la publication actuelle.
• Introduisez une nouvelle étiquette de version majeure (v2) pour les modifications qui vont casser les workflows existants.
• Publiez les versions majeures avec une étiquette bêta pour indiquer leur état, par exemple v2-beta. Vous pouvez supprimer l’étiquette -beta une fois que la publication est prête.

Voici quelques exemples de chacune des options.

steps:
    - uses: actions/javascript-action@v1
    - uses: actions/javascript-action@v1.0.1
    - uses: actions/javascript-action@v1-beta

Utiliser un SHA de commit

Les étiquettes sont utiles et largement utilisées, mais un des inconvénients de l’utilisation d’étiquettes est qu’elles peuvent être supprimées ou déplacées. Avec Git, chaque commit reçoit une valeur de SHA calculée, qui est unique et ne peut pas être modifiée. L’utilisation d’un SHA de commit pour le versioning vous offre le moyen le plus fiable et le plus sûr pour gérer les versions et utiliser une action. Cependant, dans Git, vous pouvez souvent abréger le hachage SHA aux premiers caractères : Git va reconnaître la référence. Si vous utilisez le SHA de commit pour la gestion des versions, vous devez utiliser la valeur SHA complète et non pas la valeur abrégée.

steps:
    - uses: actions/javascript-action@2522385f6f7ba04fe7327647b213799853a8f55c

Publier une action sur GitHub Marketplace

Quand vous êtes prêt à partager votre action avec la communauté GitHub, vous pouvez la publier sur GitHub Marketplace et atteindre des millions d’utilisateurs de GitHub. Les actions publiées sur GitHub Marketplace sont publiées immédiatement si toutes les conditions sont remplies. Les actions qui ne répondent pas aux exigences doivent être examinées par GitHub avant d’être publiées. Vous devez vérifier que le dépôt contient uniquement le fichier de métadonnées, le code et les fichiers nécessaires pour l’action. La création d’un dépôt unique pour l’action vous permet d’étiqueter, publier et empaqueter le code dans une même unité. GitHub utilise également les métadonnées de l’action sur votre page GitHub Marketplace.

Voici les conditions à remplir pour publier une action sur GitHub Marketplace. Elles s’appliquent à la fois aux actions basées sur des conteneurs Docker et aux actions basées sur JavaScript :

• L’action doit être dans un dépôt public.
• Chaque dépôt doit contenir une seule action.
• Le fichier de métadonnées de l’action (action.yml ou action.yaml) doit se trouver dans le répertoire racine du dépôt.
• name dans le fichier de métadonnées de l’action doit être unique sur GitHub Marketplace.
  • Le nom ne peut pas correspondre à un utilisateur ou à une organisation sur GitHub, sauf si l’utilisateur ou le propriétaire de l’organisation publie l’action. Par exemple, seule l’organisation GitHub peut publier une action nommée github.
  • Le name ne peut pas correspondre à une catégorie existante de GitHub Marketplace.
  • Le name ne peut pas correspondre à une fonctionnalité existante de GitHub.

Vous pouvez ajouter l’action que vous avez créée à GitHub Marketplace en l’étiquetant comme nouvelle version, puis en la publiant. Quelques étapes guidées dans GitHub vous permettent de publier une version de votre action. Vous pouvez trouver plus d’informations sur ces étapes dans la section Récapitulatif à la fin de ce module.