Workflow commands for GitHub Actions

À propos des commandes de workflow

Les actions peuvent communiquer avec la machine de l’exécuteur pour définir des variables d’environnement, générer des valeurs utilisées par d’autres actions, ajouter des messages de débogage aux journaux de sortie, entre autres tâches.

La plupart des commandes de workflow utilisent la commande echo dans un format spécifique, tandis que d’autres sont appelées en écrivant dans un fichier. Pour plus d’informations, consultez « Fichiers d’environnement ».

Exemple de commande de workflow

echo "::workflow-command parameter1={data},parameter2={data}::{command value}"

Write-Output "::workflow-command parameter1={data},parameter2={data}::{command value}"

Utilisation de commandes de workflow pour accéder aux fonctions du kit de ressources

Les actions/le kit de ressources incluent un certain nombre de fonctions qui peuvent être exécutées en tant que commandes de workflow. Utilisez la syntaxe :: pour exécuter les commandes de workflow dans votre fichier YAML. Ces commandes sont ensuite envoyées à l’exécuteur via stdout. Par exemple, au lieu d’utiliser du code pour créer une annotation d’erreur, comme ci-dessous :

core.error('Missing semicolon', {file: 'app.js', startLine: 1})

Exemple : Création d’une annotation pour une erreur

Vous pouvez utiliser la commande error dans votre workflow pour créer la même annotation d’erreur :

      - name: Create annotation for build error
        run: echo "::error file=app.js,line=1::Missing semicolon"

      - name: Create annotation for build error
        run: Write-Output "::error file=app.js,line=1::Missing semicolon"

Le tableau suivant montre quelles fonctions du kit de ressources sont disponibles dans un workflow :

Définition d’un message de débogage

Imprime un message de débogage dans le journal. Vous devez créer un secret nommé ACTIONS_STEP_DEBUG avec la valeur true pour afficher les messages de débogage définis par cette commande dans le journal. Pour plus d’informations, consultez « Enabling debug logging ».

::debug::{message}

Exemple : Définition d’un message de débogage

echo "::debug::Set the Octocat variable"

Write-Output "::debug::Set the Octocat variable"

Définition d’un message de notification

Crée un message de notification et l’imprime dans le journal. Ce message crée une annotation, qui peut associer le message à un fichier particulier de votre dépôt. Votre message peut éventuellement spécifier une position dans le fichier.

::notice file={name},line={line},endLine={endLine},title={title}::{message}

Exemple : Définition d’un message de notification

echo "::notice file=app.js,line=1,col=5,endColumn=7::Missing semicolon"

Write-Output "::notice file=app.js,line=1,col=5,endColumn=7::Missing semicolon"

Définition d’un message d’avertissement

Crée un message d’avertissement et l’imprime dans le journal. Ce message crée une annotation, qui peut associer le message à un fichier particulier de votre dépôt. Votre message peut éventuellement spécifier une position dans le fichier.

::warning file={name},line={line},endLine={endLine},title={title}::{message}

Exemple : Définition d’un message d’avertissement

echo "::warning file=app.js,line=1,col=5,endColumn=7::Missing semicolon"

Write-Output "::warning file=app.js,line=1,col=5,endColumn=7::Missing semicolon"

Définition d’un message d’erreur

Crée un message d’erreur et l’imprime dans le journal. Ce message crée une annotation, qui peut associer le message à un fichier particulier de votre dépôt. Votre message peut éventuellement spécifier une position dans le fichier.

::error file={name},line={line},endLine={endLine},title={title}::{message}

Exemple : Définition d’un message d’erreur

echo "::error file=app.js,line=1,col=5,endColumn=7::Missing semicolon"

Write-Output "::error file=app.js,line=1,col=5,endColumn=7::Missing semicolon"

Regroupement de lignes de journal

Crée un groupe extensible dans le journal. Pour créer un groupe, utilisez la commande group et spécifiez un titre (title). Tout ce que vous imprimez dans le journal entre les commandes group et endgroup est imbriqué dans une entrée extensible dans le journal.

::group::{title}
::endgroup::

Exemple : Regroupement de lignes de journal

jobs:
  bash-example:
    runs-on: ubuntu-latest
    steps:
      - name: Group of log lines
        run: |
            echo "::group::My title"
            echo "Inside group"
            echo "::endgroup::"

jobs:
  powershell-example:
    runs-on: windows-latest
    steps:
      - name: Group of log lines
        run: |
            Write-Output "::group::My title"
            Write-Output "Inside group"
            Write-Output "::endgroup::"

Masquage d’une valeur dans le journal

::add-mask::{value}

Le masquage d’une valeur empêche l’impression d’une chaîne ou d’une variable dans le journal. Chaque mot masqué séparé par des espaces blancs est remplacé par le caractère *. Vous pouvez utiliser une variable d’environnement ou une chaîne pour la valeur (value) du masque. Lorsque vous masquez une valeur, elle est traitée comme un secret et est éditée sur l’exécuteur. Par exemple, après avoir masqué une valeur, vous ne pouvez pas définir cette valeur en tant que sortie.

Exemple : Masquage d’une chaîne

Lorsque vous imprimez "Mona The Octocat" dans le journal, vous voyez "***".

echo "::add-mask::Mona The Octocat"

Write-Output "::add-mask::Mona The Octocat"

Exemple : Masquage d’une variable d’environnement

Lorsque vous imprimez la variable MY_NAME ou la valeur "Mona The Octocat" dans le journal, vous voyez "***" au lieu de "Mona The Octocat".

jobs:
  bash-example:
    runs-on: ubuntu-latest
    env:
      MY_NAME: "Mona The Octocat"
    steps:
      - name: bash-version
        run: echo "::add-mask::$MY_NAME"

jobs:
  powershell-example:
    runs-on: windows-latest
    env:
      MY_NAME: "Mona The Octocat"
    steps:
      - name: powershell-version
        run: Write-Output "::add-mask::$env:MY_NAME"

Arrêt et démarrage de commandes de workflow

Arrête le traitement de toutes les commandes de workflow. Cette commande spéciale vous permet de tout journaliser sans exécuter accidentellement une commande de workflow. Par exemple, vous pouvez arrêter la journalisation pour générer l’intégralité d’un script contenant des commentaires.

::stop-commands::{endtoken}

Pour arrêter le traitement des commandes de workflow, passez un jeton unique à stop-commands. Pour reprendre le traitement des commandes de workflow, passez le même jeton que celui que vous avez utilisé pour arrêter les commandes de workflow.

::{endtoken}::

Exemple : Arrêt et démarrage de commandes de workflow

jobs:
  workflow-command-job:
    runs-on: ubuntu-latest
    steps:
      - name: Disable workflow commands
        run: |
          echo '::warning:: This is a warning message, to demonstrate that commands are being processed.'
          stopMarker=$(uuidgen)
          echo "::stop-commands::$stopMarker"
          echo '::warning:: This will NOT be rendered as a warning, because stop-commands has been invoked.'
          echo "::$stopMarker::"
          echo '::warning:: This is a warning again, because stop-commands has been turned off.'

jobs:
  workflow-command-job:
    runs-on: windows-latest
    steps:
      - name: Disable workflow commands
        run: |
          Write-Output '::warning:: This is a warning message, to demonstrate that commands are being processed.'
          $stopMarker = New-Guid
          Write-Output "::stop-commands::$stopMarker"
          Write-Output '::warning:: This will NOT be rendered as a warning, because stop-commands has been invoked.'
          Write-Output "::$stopMarker::"
          Write-Output '::warning:: This is a warning again, because stop-commands has been turned off.'

Envoi de valeurs aux actions de préalables (pre) et ultérieures (post)

Vous pouvez créer des variables d’environnement pour les partager avec les actions pre: ou post: de votre workflow en écrivant sur le fichier situé dans GITHUB_STATE. Par exemple, vous pouvez créer un fichier avec l’action pre:, passer l’emplacement du fichier à l’action main:, puis utiliser l’action post: pour supprimer le fichier. Vous pouvez également créer un fichier avec l’action main:, passer l’emplacement du fichier à l’action post:, puis également utiliser l’action post: pour supprimer le fichier.

Si vous avez plusieurs actions pre: ou post:, vous pouvez uniquement accéder à la valeur enregistrée dans l’action où elle a été écrite dans GITHUB_STATE. Pour plus d’informations sur l’action post:, consultez « Metadata syntax for GitHub Actions ».

Le fichier GITHUB_STATE est disponible uniquement dans une action. La valeur enregistrée est stockée en tant que valeur d’environnement avec le préfixe STATE_.

Cet exemple utilise JavaScript pour écrire dans le fichier GITHUB_STATE. La variable d’environnement obtenue est nommée STATE_processID avec la valeur 12345 :

import * as fs from 'fs'
import * as os from 'os'

fs.appendFileSync(process.env.GITHUB_STATE, `processID=12345${os.EOL}`, {
  encoding: 'utf8'
})

La variable STATE_processID est ensuite disponible exclusivement pour le script de nettoyage s’exécutant sous l’action main. Cet exemple s’exécute dans main et utilise JavaScript pour afficher la valeur affectée à la variable d’environnement STATE_processID :

console.log("The running PID from the main action is: " +  process.env.STATE_processID);

Fichiers d’environnement

Pendant l’exécution d’un workflow, l’exécuteur génère des fichiers temporaires qui peuvent être utilisés pour effectuer certaines actions. Le chemin de ces fichiers est exposé via des variables d’environnement. Vous devez utiliser l’encodage UTF-8 lors de l’écriture dans ces fichiers pour garantir le traitement approprié des commandes. Plusieurs commandes peuvent être écrites dans le même fichier, séparées par des sauts de ligne.

La plupart des commandes des exemples suivants utilisent des guillemets doubles pour le renvoi des chaînes, qui tenteront d’interpoler des caractères comme $ pour les noms de variables d’interpréteur de commandes. Pour toujours utiliser des valeurs littérales dans des chaînes entre guillemets, vous pouvez utiliser des guillemets simples à la place.

jobs:
  legacy-powershell-example:
    runs-on: windows-latest
    steps:
      - shell: powershell
        run: |
          "mypath" | Out-File -FilePath $env:GITHUB_PATH -Encoding utf8 -Append

jobs:
  powershell-core-example:
    runs-on: windows-latest
    steps:
      - shell: pwsh
        run: |
          "mypath" >> $env:GITHUB_PATH

Définition d’une variable d’environnement

echo "{environment_variable_name}={value}" >> $GITHUB_ENV

Vous pouvez rendre une variable d’environnement disponible pour toutes les étapes suivantes d’un travail de workflow en définissant ou en mettant à jour la variable d’environnement, puis en écrivant ceci dans le fichier d’environnement GITHUB_ENV. L’étape qui crée ou met à jour la variable d’environnement n’a pas accès à la nouvelle valeur, mais toutes les étapes suivantes d’un travail y ont accès. Les noms des variables d’environnement respectent la casse et vous pouvez inclure des signes de ponctuation. Pour plus d’informations, consultez « Variables ».

Exemple d’écriture d’une variable d’environnement dans GITHUB_ENV

steps:
  - name: Set the value
    id: step_one
    run: |
      echo "action_state=yellow" >> $GITHUB_ENV
  - name: Use the value
    id: step_two
    run: |
      echo "${{ env.action_state }}" # This will output 'yellow'

steps:
  - name: Set the value
    id: step_one
    run: |
      "action_state=yellow" >> $env:GITHUB_ENV
  - name: Use the value
    id: step_two
    run: |
      Write-Output "${{ env.action_state }}" # This will output 'yellow'

Chaînes multilignes

Pour les chaînes multilignes, vous pouvez utiliser un délimiteur avec la syntaxe suivante.

{name}<<{delimiter}
{value}
{delimiter}

Exemple d’une chaîne multiligne

Cet exemple sélectionne une valeur aléatoire pour $EOF comme délimiteur et définit la variable d’environnement JSON_RESPONSE sur la valeur de la réponse curl.

steps:
  - name: Set the value in bash
    id: step_one
    run: |
      EOF=$(dd if=/dev/urandom bs=15 count=1 status=none | base64)
      echo "JSON_RESPONSE<<$EOF" >> $GITHUB_ENV
      curl https://example.com >> $GITHUB_ENV
      echo "$EOF" >> $GITHUB_ENV

steps:
  - name: Set the value in pwsh
    id: step_one
    run: |
      -join (1..15 | ForEach {[char]((48..57)+(65..90)+(97..122) | Get-Random)}) | set EOF
      "JSON_RESPONSE<<$EOF" >> $env:GITHUB_ENV
      (Invoke-WebRequest -Uri "https://example.com").Content >> $env:GITHUB_ENV
      "$EOF" >> $env:GITHUB_ENV
    shell: pwsh

Définition d’un paramètre de sortie

Définit le paramètre de sortie d’une étape. Notez que l’étape a besoin d’un id pour être définie afin de récupérer ensuite la valeur de sortie.

echo "{name}={value}" >> $GITHUB_OUTPUT

"{name}=value" >> $env:GITHUB_OUTPUT

Exemple de définition d’un paramètre de sortie

      - name: Set color
        id: random-color-generator
        run: echo "SELECTED_COLOR=green" >> $GITHUB_OUTPUT
      - name: Get color
        run: echo "The selected color is ${{ steps.random-color-generator.outputs.SELECTED_COLOR }}"

      - name: Set color
        id: random-color-generator
        run: |
            "SELECTED_COLOR=green" >> $env:GITHUB_OUTPUT
      - name: Get color
        run: Write-Output "The selected color is ${{ steps.random-color-generator.outputs.SELECTED_COLOR }}"

Ajout d’un résumé de travail

echo "{markdown content}" >> $GITHUB_STEP_SUMMARY

"{markdown content}" >> $env:GITHUB_STEP_SUMMARY

Vous pouvez définir un Markdown personnalisé pour chaque travail afin qu’il s’affiche sur la page Résumé d’une exécution de workflow. Vous pouvez utiliser des résumés de travaux pour afficher et regrouper du contenu unique, tel que des résumés de résultats de test, afin qu’un utilisateur qui affiche le résultat d’une exécution de workflow n’ait pas besoin d’accéder aux journaux pour voir des informations importantes relatives à l’exécution, telles que les défaillances.

Les résumés de travaux prennent en charge Markdown adapté GitHub et vous pouvez ajouter votre contenu Markdown pour une étape au fichier d’environnement GITHUB_STEP_SUMMARY. GITHUB_STEP_SUMMARY est unique pour chaque étape d’un travail. Pour plus d’informations sur le fichier par étape auquel GITHUB_STEP_SUMMARY fait référence, consultez « Fichiers d’environnement ».

Lorsqu’un travail se termine, les résumés de toutes les étapes d’un travail sont regroupés dans un résumé de travail unique et sont affichés sur la page résumé de l’exécution du workflow. Si plusieurs travaux génèrent des résumés, les résumés des travaux sont classés par heure d’achèvement du travail.

Exemple d’ajout d’un résumé de travail

echo "### Hello world! :rocket:" >> $GITHUB_STEP_SUMMARY

"### Hello world! :rocket:" >> $env:GITHUB_STEP_SUMMARY

Contenu Markdown multiligne

Pour le contenu Markdown multiligne, vous pouvez utiliser >> pour ajouter en continu du contenu pour l’étape actuelle. Avec chaque opération d’ajout, un caractère de nouvelle ligne est automatiquement ajouté.

Exemple de contenu Markdown multiligne

- name: Generate list using Markdown
  run: |
    echo "This is the lead in sentence for the list" >> $GITHUB_STEP_SUMMARY
    echo "" >> $GITHUB_STEP_SUMMARY # this is a blank line
    echo "- Lets add a bullet point" >> $GITHUB_STEP_SUMMARY
    echo "- Lets add a second bullet point" >> $GITHUB_STEP_SUMMARY
    echo "- How about a third one?" >> $GITHUB_STEP_SUMMARY

- name: Generate list using Markdown
  run: |
    "This is the lead in sentence for the list" >> $env:GITHUB_STEP_SUMMARY
    "" >> $env:GITHUB_STEP_SUMMARY # this is a blank line
    "- Lets add a bullet point" >> $env:GITHUB_STEP_SUMMARY
    "- Lets add a second bullet point" >> $env:GITHUB_STEP_SUMMARY
    "- How about a third one?" >> $env:GITHUB_STEP_SUMMARY

Remplacement de résumés des travaux

Pour effacer tout le contenu de l’étape actuelle, vous pouvez utiliser > pour remplacer tout contenu précédemment ajouté.

Exemple de remplacement de résumés de travaux

- name: Overwrite Markdown
  run: |
    echo "Adding some Markdown content" >> $GITHUB_STEP_SUMMARY
    echo "There was an error, we need to clear the previous Markdown with some new content." > $GITHUB_STEP_SUMMARY

- name: Overwrite Markdown
  run: |
    "Adding some Markdown content" >> $env:GITHUB_STEP_SUMMARY
    "There was an error, we need to clear the previous Markdown with some new content." > $env:GITHUB_STEP_SUMMARY

Suppression de résumés de travaux

Pour supprimer complètement un résumé de l’étape actuelle, le fichier auquel GITHUB_STEP_SUMMARY fait référence peut être supprimé.

Exemple de suppression de résumés de travaux

- name: Delete all summary content
  run: |
    echo "Adding Markdown content that we want to remove before the step ends" >> $GITHUB_STEP_SUMMARY
    rm $GITHUB_STEP_SUMMARY

- name: Delete all summary content
  run: |
    "Adding Markdown content that we want to remove before the step ends" >> $env:GITHUB_STEP_SUMMARY
    rm $env:GITHUB_STEP_SUMMARY

Une fois l’étape terminée, les résumés des travaux sont chargés et les étapes suivantes ne peuvent pas modifier le contenu Markdown précédemment chargé. Les résumés masquent automatiquement les secrets qui peuvent avoir été ajoutés accidentellement. Si un résumé de travail contient des informations sensibles qui doivent être supprimées, vous pouvez supprimer l’exécution entière du workflow pour supprimer tous ses résumés de travaux. Pour plus d’informations, consultez « Suppression d’une exécution de workflow ».

Isolation et limites des étapes

Les résumés de travaux sont isolés entre les étapes et chaque étape est limitée à une taille maximale de 1MiB. L’isolation est appliquée entre les étapes afin que Markdown potentiellement mal formé à partir d’une seule étape ne puisse pas interrompre le rendu Markdown pour les étapes suivantes. Si plus de 1MiB de contenu est ajouté pour une étape, le chargement de l’étape échoue et une annotation d’erreur est créée. Télécharger des défaillances de résumés des travaux n’affecte pas l’état global d’une étape ou d’un travail. Un maximum de 20 résumés de travaux à partir des étapes s’affichent par travail.

Ajout d’un chemin système

Ajoute un répertoire à la variable système PATH et le rend automatiquement disponible pour toutes les actions suivantes dans le travail actuel. L’action en cours d’exécution ne peut pas accéder à la variable de chemin mise à jour. Pour afficher les chemins actuellement définis pour votre travail, vous pouvez utiliser echo "$PATH" dans une étape ou une action.

echo "{path}" >> $GITHUB_PATH

"{path}" >> $env:GITHUB_PATH

Exemple d’ajout d’un chemin système

echo "$HOME/.local/bin" >> $GITHUB_PATH

"$env:HOMEPATH/.local/bin" >> $env:GITHUB_PATH