Gestion des actions personnalisées

Apprenez à créer et à gérer vos propres actions, et à personnaliser les actions partagées par la communauté GitHub.

Dans cet article

Choisir un emplacement pour votre action

Si vous développez une action pour que d’autres personnes l’utilisent, nous vous recommandons de stocker l’action dans son propre dépôt au lieu de la regrouper avec d’autres codes d’application. Ceci vous permet de versionner, d’effectuer le suivi et de publier l’action comme vous le feriez pour n’importe quel autre logiciel.

Le stockage d’une action dans son propre dépôt facilite la découverte de l’action par la communauté GitHub, restreint l’étendue de la base de code pour les développeurs qui corrigent les problèmes et étendent l’action, et dissocient le versioning de l’action de celui des autres codes d’application.

Si vous créez une action que vous ne prévoyez pas de mettre à disposition d’autres personnes, vous pouvez stocker les fichiers de l’action dans 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 vous recommandons de stocker les actions dans le référentiel .github. Par exemple : .github/actions/action-a et .github/actions/action-b.

Garantir la compatibilité avec les autres plateformes

De nombreuses personnes accèdent à GitHub dans un domaine autre que GitHub.com, comme GHE.com ou un domaine personnalisé pour GitHub Enterprise Server.

Pour vous assurer que votre action est compatible avec d’autres plateformes, n’utilisez aucune référence codée en dur aux URL d’API telles que https://api.github.com. Au lieu de cela, vous pouvez :

  • Utiliser des variables d’environnement (consultez « Références des variables ») :

    • Pour l’API REST, utilisez la variable d’environnement GITHUB_API_URL.
    • Pour GraphQL, utilisez la variable d’environnement GITHUB_GRAPHQL_URL.

  • Utilisez un kit de ressources tel que @actions/github, qui peut définir automatiquement les URL correctes.

Using release management for actions

Cette section explique comment utiliser la gestion des mises en production pour distribuer les mises à jour de vos actions de manière prévisible.

Bonnes pratiques concernant la gestion des mises en production

Si vous développez une action pour que d’autres personnes l’utilisent, nous vous recommandons d’utiliser la gestion des mises en production afin de contrôler la façon dont vous distribuez les mises à jour. Les utilisateurs peuvent s’attendre à ce que la version corrective d’une action inclue les correctifs critiques et les correctifs de sécurité nécessaires, tout en restant compatibles avec leurs workflows existants. Il est conseillé de publier une nouvelle version majeure chaque fois que vos modifications affectent la compatibilité.

Dans cette approche de gestion des mises en production, les utilisateurs ne doivent pas référencer la branche par défaut d’une action, car celle-ci est susceptible de contenir le code le plus récent et donc, d’être instable. Vous pouvez plutôt recommander à vos utilisateurs de spécifier une version majeure lorsqu’ils utilisent votre action, et les diriger vers une version plus spécifique uniquement s’ils rencontrent des problèmes.

Pour utiliser une version d’action spécifique, les utilisateurs peuvent configurer leur workflow GitHub Actions pour cibler une étiquette, un SHA de commit ou une branche nommée dans le cadre d’une publication.

Utilisation d’étiquettes pour la gestion des mises en production

Nous vous recommandons d’utiliser des étiquettes pour la gestion des mises en production des actions. Cette approche permet aux utilisateurs de facilement distinguer les versions majeures des versions mineures.

  • 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).
  • Créez une version à l’aide du versioning sémantique. Pour plus d’informations, consultez « Gestion des mises en production dans un référentiel ».
  • 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. Pour plus d’informations, consultez « Git basics - tagging ».
  • Introduisez une nouvelle étiquette de version majeure (v2) pour les modifications qui vont casser les workflows existants. Par exemple, la modification des entrées d’une action constituerait un changement cassant.
  • Les versions principales peuvent être initialement publiées avec une étiquette beta pour indiquer leur état, par exemple v2-beta. L’étiquette -beta peut ensuite être supprimée une fois la version prête.

Cet exemple montre comment un utilisateur peut référencer une étiquette de version principale :

steps:
    - uses: actions/javascript-action@v1

Cet exemple montre comment un utilisateur peut référencer une étiquette de version corrective :

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

Utilisation de branches pour la gestion des mises en production

Si vous préférez utiliser des noms de branche pour la gestion des mises en production, cet exemple montre comment référencer une branche nommée :

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

Utilisation du SHA d’un commit pour la gestion des mises en production

Chaque commit Git reçoit une valeur de SHA calculée, qui est unique et non modifiable. Les utilisateurs de votre action peuvent préférer s’appuyer sur la valeur SHA d’un commit, car cette approche peut être plus fiable que la spécification d’une étiquette, qui peut être supprimée ou déplacée. Toutefois, cela signifie que les utilisateurs ne recevront pas les prochaines mises à jour de l’action. Vous devez utiliser la valeur SHA complète d’un commit et non une valeur abrégée.

steps:
    - uses: actions/javascript-action@a824008085750b8e136effc585c3cd6082bd575f

Création d’un fichier README pour votre action

Nous vous recommandons de créer un fichier README pour aider les utilisateurs à utiliser votre action. Vous pouvez inclure les informations suivantes dans votre README.md :

  • 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