Metadata syntax for GitHub Actions

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 : num-octocats et octocat-eye-color. L’entrée num-octocats n’est pas obligatoire et a par défaut la valeur 1. octocat-eye-color est obligatoire et n’a pas de valeur par défaut.

Remarque : les flux de travail utilisant required: true ne retournent pas automatiquement d’erreur si l’entrée n’est pas spécifiée pour les événements qui déclenchent automatiquement des exécutions de flux de travail. Si vous avez défini required: true dans votre fichier de flux de travail et que vous utilisez workflow_dispatch pour exécuter manuellement le flux de travail, vous devrez spécifier des entrées sur GitHub. Pour plus d’informations, consultez « Événements qui déclenchent des flux de travail ».

Les fichiers de workflow qui utilisent cette action peuvent utiliser le mot clé with afin de définir une valeur d’entrée pour octocat-eye-color. Pour plus d’informations sur la syntaxe with, consultez « Workflow syntax for GitHub Actions ».

inputs:
  num-octocats:
    description: 'Number of Octocats'
    required: false
    default: '1'
  octocat-eye-color:
    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 « Creating a Docker container action ».

Par exemple, si un workflow a défini les entrées num-octocats et octocat-eye-color, le code d’action peut lire les valeurs des entrées à l’aide des variables d’environnement INPUT_NUM-OCTOCATS et INPUT_OCTOCAT-EYE-COLOR.

`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 des sorties dans une action, consultez « Workflow commands for 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 "random-id=$(echo $RANDOM)" >> $GITHUB_OUTPUT
      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 v16

runs:
  using: 'node16'
  main: 'main.js'

`runs.using` pour les actions JavaScript

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

Utilisez node16 pour Node.js v16.

`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: 'node16'
  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: 'node16'
  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` pour les actions composites

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 « Contextes ».

`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 dans « Workflow syntax for GitHub Actions ». Obligatoire si run est défini.

`runs.steps[*].if`

Facultatif Vous pouvez utiliser la condition if pour empêcher l’exécution d’une étape si une condition n’est pas remplie. Vous pouvez utiliser n’importe quel contexte et n’importe quelle expression pris en charge pour créer un conditionnel.

Quand vous utilisez des expressions dans un conditionnel if, vous pouvez omettre la syntaxe de l’expression ${{ }} parce que GitHub Actions évalue automatiquement le conditionnel if en tant qu’expression. Toutefois, cette exception ne s’applique pas partout.

Vous devez utiliser la syntaxe d’expression ${{ }} ou l’échappement avec '', "" ou () lorsque l’expression commence par !, car ! est une notation réservée au format YAML. Par exemple :

if: ${{ ! startsWith(github.ref, 'refs/tags/') }}

Pour plus d’informations, consultez « Expressions ».

Exemple : Utilisation des contextes

Cette étape s’exécute uniquement lorsque le type d’événement est pull_request et que l’action d’événement est unassigned.

steps:
  - run: echo This event is a pull request that had an assignee removed.
    if: ${{ github.event_name == 'pull_request' && github.event.action == 'unassigned' }}

Exemple : Utilisation des fonctions de vérification d’état

my backup step s’exécute uniquement en cas d’échec de l’étape précédente d’une action composite. Pour plus d’informations, consultez « Expressions ».

steps:
  - name: My first step
    uses: octo-org/action-name@main
  - name: My backup step
    if: ${{ failure() }}
    uses: actions/heroku@1.0.0

`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@8f4b7f84864484a7bf31766abe9204da3cbe65b3
    # Reference the major version of a release
    - uses: actions/checkout@v4
    # Reference a specific version
    - uses: actions/checkout@v4.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.steps[*].continue-on-error`

Facultatif Empêche l’action d’échouer lorsqu’une étape échoue. Définissez la valeur true pour permettre à l’action de réussir en cas d’échec de cette étape.

`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` pour les actions de conteneur Docker

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 la façon dont s’exécute entrypoint, consultez « Prise en charge des fichiers 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 :

Documentez les arguments requis dans le fichier README de l’action et omettez-les de l’instruction CMD.
Utilisez les valeurs par défaut qui autorisent l’utilisation de l’action sans spécifier aucune valeur args.
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 des fichiers 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'

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

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

Metadata syntax for GitHub Actions

Dans cet article