Skip to main content

Cette version de GitHub Enterprise a été abandonnée le 2023-01-18. Aucune publication de correctifs n’est effectuée, même pour les problèmes de sécurité critiques. Pour de meilleures performances, une sécurité améliorée et de nouvelles fonctionnalités, effectuez une mise à niveau vers la dernière version de GitHub Enterprise. Pour obtenir de l’aide sur la mise à niveau, contactez le support GitHub Enterprise.

Metadata syntax for GitHub Actions

Vous pouvez créer des actions pour effectuer des tâches dans votre référentiel. Les actions nécessitent un fichier de métadonnées qui utilise la syntaxe YAML.

Remarque : Les exécuteurs hébergés sur GitHub ne sont pas pris en charge sur GitHub Enterprise Server. Vous pouvez voir plus d’informations sur le support futur planifié dans la GitHub public roadmap.

À propos de la syntaxe YAML pour GitHub Actions

Toutes les actions nécessitent un fichier de métadonnées. Le nom de fichier des métadonnées doit être soit action.yml, soit action.yaml. Les données du fichier de métadonnées définissent les entrées et les sorties, et exécutent la configuration de votre action.

Les fichiers de métadonnées d’action utilisent la syntaxe YAML. Si vous débutez avec YAML, vous pouvez lire « Learn YAML in five minutes ».

name

Obligatoire Le nom de votre action. GitHub affiche name sous l’onglet Actions pour identifier visuellement les actions de chaque travail.

author

Facultatif Le nom de l’auteur de l’action.

description

Obligatoire Une brève description de l’action.

inputs

Facultatif Les paramètres d’entrée vous permettent de spécifier les données que l’action s’attend à utiliser lors de l’exécution. GitHub stocke les paramètres d’entrée en tant que variables d’environnement. Les lettres majuscules des ID d’entrée sont converties en lettres minuscules pendant l’exécution. Nous vous recommandons d’utiliser des ID d’entrée en minuscules.

Exemple Spécifier des entrées

Cet exemple configure deux entrées : numOctocats et octocatEyeColor. L’entrée numOctocats n’est pas obligatoire et a par défaut la valeur « 1 ». L’entrée octocatEyeColor est obligatoire et n’a pas de valeur par défaut. Les fichiers de workflow qui utilisent cette action doivent utiliser le mot clé with afin de définir une valeur d’entrée pour octocatEyeColor. Pour plus d’informations sur la syntaxe with, consultez « Syntaxe de workflow pour GitHub Actions ».

inputs:
  numOctocats:
    description: 'Number of Octocats'
    required: false
    default: '1'
  octocatEyeColor:
    description: 'Eye color of the Octocats'
    required: true

Si vous spécifiez une entrée dans un fichier de workflow ou utilisez une valeur d’entrée par défaut, GitHub crée une variable d’environnement pour l’entrée avec le nom INPUT_<VARIABLE_NAME>. La variable d’environnement créée convertit les noms d’entrée en lettres majuscules et remplace les espaces par des caractères _.

Si l’action est écrite à l’aide d’un composite, elle n’obtiendra pas automatiquement INPUT_<VARIABLE_NAME>. Si la conversion ne se produit pas, vous pouvez modifier ces entrées manuellement.

Pour accéder à la variable d’environnement dans une action de conteneur Docker, vous devez passer l’entrée à l’aide du mot clé dans le fichier de métadonnées d’action args. Pour plus d’informations sur le fichier de métadonnées des actions de conteneur Docker, consultez « Création d’une action de conteneur Docker ».

Par exemple, si un workflow a défini les entrées numOctocats et octocatEyeColor, le code d’action peut lire les valeurs des entrées à l’aide des variables d’environnement INPUT_NUMOCTOCATS et INPUT_OCTOCATEYECOLOR.

inputs.<input_id>

Obligatoire Un identificateur string à associer à l’entrée. La valeur de <input_id> est une carte des métadonnées de l’entrée. <input_id> doit être un identificateur unique dans l’objet inputs. <input_id> doit commencer par une lettre ou par _, et contenir uniquement des caractères alphanumériques, des - ou des _.

inputs.<input_id>.description

Obligatoire Une description string des paramètres d’entrée.

inputs.<input_id>.required

Facultatif Un boolean pour indiquer si l’action nécessite le paramètre d’entrée. À définir sur true si le paramètre est obligatoire.

inputs.<input_id>.default

Facultatif Un string représentant la valeur par défaut. La valeur par défaut est utilisée lorsqu’un paramètre d’entrée n’est pas spécifié dans un fichier de workflow.

inputs.<input_id>.deprecationMessage

Facultatif Si le paramètre d’entrée est utilisé, cette string est journalisée en tant que message d’avertissement. Vous pouvez utiliser cet avertissement pour informer les utilisateurs que l’entrée est dépréciée et leur proposer des alternatives.

outputs pour les actions de conteneur Docker et JavaScript

Facultatif Les paramètres de sortie vous permettent de déclarer les données qu’une action définit. Les actions qui s’exécutent par la suite dans un workflow peuvent utiliser le jeu de données de sortie des actions précédemment exécutées. Par exemple, si vous avez une action qui a réalisé l’addition de deux entrées (x + y = z), l’action peut générer la somme (z) d’autres actions afin de l’utiliser en tant qu’entrée.

Les sorties sont des chaînes Unicode, et leur taille maximale est de 1 Mo. La taille totale maximale de toutes les sorties d’une exécution de workflow est de 50 Mo.

Si vous ne déclarez pas de sortie dans votre fichier de métadonnées d’action, vous pouvez toujours définir des sorties et les utiliser dans un workflow. Pour plus d’informations sur la définition de sorties dans une action, consultez « Commandes de workflow pour GitHub Actions ».

Exemple : Déclaration de sorties pour les actions de conteneur Docker et JavaScript

outputs:
  sum: # id of the output
    description: 'The sum of the inputs'

outputs.<output_id>

Obligatoire Un identificateur string à associer à la sortie. La valeur de <output_id> est une carte des métadonnées de la sortie. <output_id> doit être un identificateur unique dans l’objet outputs. <output_id> doit commencer par une lettre ou par _, et contenir uniquement des caractères alphanumériques, des - ou des _.

outputs.<output_id>.description

Obligatoire Une description string des paramètres de sortie.

outputs pour les actions composites

Optionnel Les outputs utilisent les mêmes paramètres que outputs.<output_id> et outputs.<output_id>.description (voir « outputs pour les actions de conteneur Docker et JavaScript »), mais ils comprennent également le jeton value.

Les sorties sont des chaînes Unicode, et leur taille maximale est de 1 Mo. La taille totale maximale de toutes les sorties d’une exécution de workflow est de 50 Mo.

Exemple : Déclaration de sorties pour les actions composites

outputs:
  random-number:
    description: "Random number"
    value: ${{ steps.random-number-generator.outputs.random-id }}
runs:
  using: "composite"
  steps:
    - id: random-number-generator
      run: echo "::set-output name=random-id::$(echo $RANDOM)"
      shell: bash

outputs.<output_id>.value

Obligatoire La valeur à laquelle le paramètre de sortie sera mappé. Vous pouvez définir cette valeur sur une string ou sur une expression avec un contexte. Par exemple, vous pouvez utiliser le contexte steps pour définir la value d’une sortie sur la valeur de sortie d’une étape.

Pour plus d’informations sur l’utilisation de la syntaxe de contexte, consultez « Contextes ».

runs

Obligatoire Spécifie s’il s’agit d’une action JavaScript, d’une action composite ou d’une action de conteneur Docker, ainsi que la façon dont l’action est exécutée.

runs pour les actions JavaScript

Obligatoire Configure le chemin du code de l’action et le runtime utilisé pour exécuter le code.

Exemple : Utilisation de Node.js v12

runs:
  using: 'node12'
  main: 'main.js'

runs.using

Obligatoire Le runtime utilisé pour exécuter le code spécifié dans main.

  • Utiliser node12 pour Node.js v12.

runs.main

Obligatoire Le fichier qui contient votre code d’action. Le runtime spécifié dans using exécute ce fichier.

runs.pre

Facultatif Permet d’exécuter un script au début d’un travail, avant que l’action main: ne commence. Par exemple, vous pouvez utiliser pre: pour exécuter un script de configuration prérequis. Le runtime spécifié avec la syntaxe using exécute ce fichier. L’action pre: s’exécute toujours par défaut, mais vous pouvez modifier cela en utilisant runs.pre-if.

Dans cet exemple, l’action pre: exécute un script appelé setup.js :

runs:
  using: 'node12'
  pre: 'setup.js'
  main: 'index.js'
  post: 'cleanup.js'

runs.pre-if

Facultatif Permet de définir des conditions pour l’exécution de l’action pre:. L’action pre: s’exécute uniquement si les conditions de pre-if sont remplies. Si les conditions ne sont pas définies, pre-if aura always() comme valeur par défaut. Dans pre-if, les fonctions de vérification d’état évaluent l’état du travail, et non l’état de l’action.

Notez que le contexte step n’est pas disponible, car aucune étape n’a encore été exécutée.

Dans cet exemple, cleanup.js exécute uniquement les exécuteurs :

  pre: 'cleanup.js'
  pre-if: runner.os == 'linux'

runs.post

Optionnel Permet d’exécuter un script à la fin d’un travail, une fois l’action main: terminée. Par exemple, vous pouvez utiliser post: pour arrêter certains processus ou supprimer des fichiers inutiles. Le runtime spécifié avec la syntaxe using exécute ce fichier.

Dans cet exemple, l’action post: exécute un script appelé cleanup.js :

runs:
  using: 'node12'
  main: 'index.js'
  post: 'cleanup.js'

L’action post: s’exécute toujours par défaut, mais vous pouvez modifier cela en utilisant post-if.

runs.post-if

Facultatif Permet de définir des conditions pour l’exécution de l’action post:. L’action post: s’exécute uniquement si les conditions de post-if sont remplies. Si les conditions ne sont pas définies, post-if aura always() comme valeur par défaut. Dans post-if, les fonctions de vérification d’état évaluent l’état du travail, et non l’état de l’action.

Par exemple, ce cleanup.js ne s’exécutera que sur les exécuteurs Linux :

  post: 'cleanup.js'
  post-if: runner.os == 'linux'

runs pour les actions composites

Obligatoire Configure le chemin de l’action composite.

runs.using

Obligatoire Vous devez définir cette valeur sur 'composite'.

runs.steps

Obligatoire Les étapes que vous prévoyez d’exécuter dans cette action. Il peut s’agir d’étapes run ou uses.

runs.steps[*].run

Facultatif La commande que vous souhaitez exécuter. Il peut s’agir d’un inline ou d’un script de votre dépôt d’actions :

runs:
  using: "composite"
  steps:
    - run: ${{ github.action_path }}/test/script.sh
      shell: bash

Vous pouvez également utiliser $GITHUB_ACTION_PATH :

runs:
  using: "composite"
  steps:
    - run: $GITHUB_ACTION_PATH/script.sh
      shell: bash

Pour plus d’informations, consultez « github context ».

runs.steps[*].shell

Facultatif L’interpréteur de commandes dans lequel vous souhaitez exécuter la commande. Vous pouvez utiliser l’un des interpréteurs de commandes listés ici. Obligatoire si run est défini.

runs.steps[*].name

Facultatif Le nom de l’étape composite.

runs.steps[*].id

Facultatif Un identificateur unique pour l’étape. Vous pouvez utiliser l’étape id pour référencer l’étape dans des contextes. Pour plus d’informations, consultez « Contextes ».

runs.steps[*].env

Facultatif Définit une variable d’environnement map pour cette étape uniquement. Si vous souhaitez modifier la variable d’environnement stockée dans le workflow, utilisez echo "{name}={value}" >> $GITHUB_ENV dans une étape composite.

runs.steps[*].working-directory

Facultatif Spécifie le répertoire de travail dans lequel la commande est exécutée.

runs.steps[*].uses

Facultatif Sélectionne une action à exécuter dans le cadre d’une étape de votre travail. Une action est une unité de code réutilisable. Vous pouvez utiliser une action définie dans le même dépôt que le workflow, dans un dépôt public ou dans une image conteneur Docker publiée.

Nous vous recommandons vivement d’inclure la version de l’action que vous utilisez en spécifiant un numéro d’étiquette Git ref, SHA ou Docker. Si vous ne spécifiez pas de version, cela peut arrêter vos workflows ou provoquer un comportement inattendu lorsque le propriétaire de l’action publie une mise à jour.

  • L’utilisation du SHA de commit d’une version d’action publiée est la solution la plus sûre en termes de stabilité et de sécurité.
  • L’utilisation de la version d’action majeure spécifique vous permet de recevoir des correctifs critiques et des correctifs de sécurité tout en maintenant la compatibilité. Cela garantit également que votre workflow continue de fonctionner.
  • L’utilisation de la branche par défaut d’une action peut être pratique. Toutefois, si un utilisateur publie une nouvelle version majeure avec un changement cassant, votre workflow peut s’arrêter.

Certaines actions nécessitent des entrées que vous devez définir à l’aide du mot clé with. Examinez le fichier README de l’action pour déterminer les entrées nécessaires.

runs:
  using: "composite"
  steps:
    # Reference a specific commit
    - uses: actions/checkout@a81bbbf8298c0fa03ea29cdc473d45769f953675
    # Reference the major version of a release
    - uses: actions/checkout@v2
    # Reference a specific version
    - uses: actions/checkout@v2.2.0
    # Reference a branch
    - uses: actions/checkout@main
    # References a subdirectory in a public GitHub repository at a specific branch, ref, or SHA
    - uses: actions/aws/ec2@main
    # References a local action
    - uses: ./.github/actions/my-action
    # References a docker public registry action
    - uses: docker://gcr.io/cloud-builders/gradle
    # Reference a docker image published on docker hub
    - uses: docker://alpine:3.8

runs.steps[*].with

Facultatif Une map des paramètres d’entrée définis par l’action. Chaque paramètre d’entrée est une paire clé-valeur. Pour plus d’informations, consultez « Exemple : Spécification d’entrées ».

runs:
  using: "composite"
  steps:
    - name: My first step
      uses: actions/hello_world@main
      with:
        first_name: Mona
        middle_name: The
        last_name: Octocat

runs pour les actions de conteneur Docker

Obligatoire Configure l’image utilisée pour l’action de conteneur Docker.

Exemple : Utilisation d’un fichier Dockerfile dans votre dépôt

runs:
  using: 'docker'
  image: 'Dockerfile'

Exemple : Utilisation d’un conteneur de registre Docker public

runs:
  using: 'docker'
  image: 'docker://debian:stretch-slim'

runs.using

Obligatoire Vous devez définir cette valeur sur 'docker'.

runs.pre-entrypoint

Facultatif Permet d’exécuter un script avant le début de l’action entrypoint. Par exemple, vous pouvez utiliser pre-entrypoint: pour exécuter un script de configuration prérequis. GitHub Actions utilise docker run pour lancer cette action et exécute le script à l’intérieur d’un nouveau conteneur qui utilise la même image de base. Cela signifie que l’état du runtime est différent de celui du conteneur principal entrypoint, et que tous les états dont vous avez besoin doivent être accessibles dans l’espace de travail HOME ou sous forme de variable STATE_. L’action pre-entrypoint: s’exécute toujours par défaut, mais vous pouvez modifier cela en utilisant runs.pre-if.

Le runtime spécifié avec la syntaxe using exécute ce fichier.

Dans cet exemple, l’action pre-entrypoint: exécute un script appelé setup.sh :

runs:
  using: 'docker'
  image: 'Dockerfile'
  args:
    - 'bzz'
  pre-entrypoint: 'setup.sh'
  entrypoint: 'main.sh'

runs.image

Obligatoire Image Docker à utiliser comme conteneur pour exécuter l’action. La valeur peut être le nom de l’image de base Docker, un Dockerfile local dans votre dépôt ou une image publique dans Docker Hub ou un autre registre. Pour référencer un Dockerfile local vers votre dépôt, le fichier doit être nommé Dockerfile. En outre, vous devez utiliser un chemin relatif à votre fichier de métadonnées d’action. L’application docker exécute ce fichier.

runs.env

Facultatif Spécifie un mappage clé/valeur des variables d’environnement à définir dans l’environnement de conteneur.

runs.entrypoint

Facultatif Remplace le ENTRYPOINT Docker dans le Dockerfile, ou définit celui-ci s’il n’a pas déjà été spécifié. Utilisez entrypoint si Dockerfile ne spécifie pas de ENTRYPOINT ou si vous souhaitez remplacer l’instruction ENTRYPOINT. Si vous omettez entrypoint, les commandes que vous spécifiez dans l’instruction Docker ENTRYPOINT s’exécuteront. L’instruction Docker ENTRYPOINT peut avoir un format shell ou un format exec. La documentation Docker ENTRYPOINT recommande d’utiliser le format exec de l’instruction ENTRYPOINT.

Pour plus d’informations sur l’exécution de entrypoint, consultez « Prise en charge de Dockerfile pour GitHub Actions ».

runs.post-entrypoint

Facultatif Permet d’exécuter un script de nettoyage une fois l’action runs.entrypoint terminée. GitHub Actions utilise docker run pour lancer cette action. Étant donné que GitHub Actions exécute le script à l’intérieur d’un nouveau conteneur à l’aide de la même image de base, l’état d’exécution est différent de celui du conteneur principal entrypoint. Vous pouvez accéder à n’importe quel état dont vous avez besoin dans l’espace de travail HOME ou en tant que variable STATE_. L’action post-entrypoint: s’exécute toujours par défaut, mais vous pouvez modifier cela en utilisant runs.post-if.

runs:
  using: 'docker'
  image: 'Dockerfile'
  args:
    - 'bzz'
  entrypoint: 'main.sh'
  post-entrypoint: 'cleanup.sh'

runs.args

Facultatif Tableau de chaînes qui définissent les entrées d’un conteneur Docker. Les entrées peuvent inclure des chaînes codées en dur. GitHub passe args au ENTRYPOINT du conteneur quand celui-ci démarre.

Les args sont utilisés à la place de l’instruction CMD dans un Dockerfile. Si vous utilisez CMD dans votre Dockerfile, utilisez les instructions classées par ordre de préférence :

  1. Documentez les arguments requis dans le fichier README de l’action et omettez-les de l’instruction CMD.
  2. Utilisez les valeurs par défaut qui autorisent l’utilisation de l’action sans spécifier aucune valeur args.
  3. Si l’action expose un indicateur --help, ou quelque chose de similaire, utilisez-le pour rendre votre action auto-documentée.

Si vous devez passer des variables d’environnement à une action, vérifiez que votre action exécute un interpréteur de commandes pour effectuer une substitution de variable. Par exemple, si votre attribut entrypoint est défini sur "sh -c", args sera exécuté dans un interpréteur de commandes. Sinon, si Dockerfile utilise un ENTRYPOINT pour exécuter la même commande ("sh -c"), args s’exécutera dans un interpréteur de commandes.

Pour plus d’informations sur l’utilisation de l’instruction CMD avec GitHub Actions, consultez « Prise en charge de Dockerfile pour GitHub Actions ».

Exemple : Définition d’arguments pour le conteneur Docker

runs:
  using: 'docker'
  image: 'Dockerfile'
  args:
    - ${{ inputs.greeting }}
    - 'foo'
    - 'bar'

branding

Facultatif Vous pouvez utiliser une couleur ainsi qu’une icône Feather pour créer un badge permettant de personnaliser et de distinguer votre action. Les badges s’affichent en regard du nom de l’action dans GitHub Marketplace.

Exemple : Configuration de la personnalisation pour une action

branding:
  icon: 'award'
  color: 'green'

branding.color

Couleur d’arrière-plan du badge. Peut être : white, yellow, blue, green, orange, red, purple ougray-dark.

branding.icon

Nom de l’icône Feather v4.28.0 à utiliser. Les icônes de marque sont omises ainsi que les icônes suivantes :

coffee (café) colonnes divide-circle divide-square
divide frown hexagon key
meh mouse-pointer smile outil
x-octagon

Voici la liste exhaustive de toutes les icônes actuellement prises en charge :

activity airplay alert-circle alert-octagon
alert-triangle align-center align-justify align-left
align-right ancre aperture archive
arrow-down-circle arrow-down-left arrow-down-right arrow-down
arrow-left-circle arrow-left arrow-right-circle arrow-right
arrow-up-circle arrow-up-left arrow-up-right arrow-up
at-sign award bar-chart-2 bar-chart
battery-charging battery bell-off clochette
bluetooth gras book-open book
signet box briefcase calendrier
camera-off caméra Caster check-circle
check-square case activée chevron-down chevron-left
chevron-right chevron-up chevrons-down chevrons-left
chevrons-right chevrons-up circle presse-papiers
horloge cloud-drizzle cloud-lightning cloud-off
cloud-rain cloud-snow cloud code
command compass copy corner-down-left
corner-down-right corner-left-down corner-left-up corner-right-down
corner-right-up corner-up-left corner-up-right cpu
credit-card crop crosshair database
supprimer disc dollar-sign download-cloud
télécharger droplet edit-2 edit-3
modifier external-link eye-off eye
fast-forward feather file-minus file-plus
file-text fichier film filter
indicateur folder-minus folder-plus dossier
gift git-branch git-commit git-merge
git-pull-request globe grid hard-drive
hash headphones heart help-circle
home image inbox info
italique couches disposition life-buoy
link-2 link list loader
lock log-in log-out mail
map-pin carte maximize-2 maximize
menu message-circle message-square mic-off
mic minimize-2 minimize minus-circle
minus-square minus monitor moon
more-horizontal more-vertical déplacer music
navigation-2 navigation octagon package
paperclip pause-circle pause pour cent
phone-call phone-forwarded phone-incoming phone-missed
phone-off phone-outgoing phone pie-chart
play-circle play plus-circle plus-square
plus pocket puissance printer
radio refresh-ccw refresh-cw répéter
rewind rotate-ccw rotate-cw rss
Enregistrer scissors recherche Envoyer
server paramètres share-2 partager
shield-off shield shopping-bag shopping-cart
lecture aléatoire sidebar skip-back skip-forward
slash contrôles Slider smartphone haut-parleur
square étoile stop-circle sun
sunrise coucher de soleil tablette étiquette
target terminal thermometer thumbs-down
thumbs-up toggle-left toggle-right trash-2
trash trending-down trending-up triangle
camion tv type parapluie
souligné déverrouiller upload-cloud upload
user-check user-minus user-plus user-x
utilisateur users video-off video
voicemail volume-1 volume-2 volume-x
volume watch wifi-off wifi
wind x-circle x-square x
zap-off zap zoom-in zoom-out