Référence des contextes

Contextes disponibles

Dans le cadre d’une expression, vous pouvez accéder aux informations de contexte à l’aide d’une syntaxe parmi deux syntaxes au choix.

• Syntaxe d’index : github['sha']
• Syntaxe de déréférencement de propriété : github.sha

Pour permettre l’utilisation de la syntaxe de déréférencement de propriété, le nom de propriété doit commencer par une lettre ou _, et contenir uniquement des caractères alphanumériques, - ou _.

Si vous tentez de déréférencer une propriété inexistante, cela aboutit à une chaîne vide.

Déterminer quand utiliser des contextes

GitHub Actions inclut une collection de variables appelées contextes et une collection similaire de variables appelées variables par défaut. Ces variables sont destinées à être utilisées à différents stades du workflow.

• Variables d’environnement par défaut : ces variables d’environnement existent uniquement sur l’exécuteur du travail. Pour plus d’informations, consultez « Références des variables ».
• Contextes : vous pouvez utiliser la plupart des contextes à n’importe quel stade du workflow, notamment quand les variables par défaut ne sont pas disponibles. Par exemple, vous pouvez utiliser des contextes avec des expressions pour effectuer un traitement initial avant que le travail soit routé vers un exécuteur. Cela vous permet d’utiliser un contexte avec le mot clé conditionnel if pour déterminer si une étape doit être exécutée. Une fois le travail en cours d’exécution, vous pouvez également récupérer des variables de contexte à partir de l’exécuteur du travail, par exemple runner.os. Pour plus d’informations sur l’emplacement où vous pouvez utiliser divers contextes au sein d’un workflow, consultez Disponibilité du contexte.

L’exemple suivant montre comment ces différents types de variables peuvent être utilisés ensemble dans un travail :

name: CI
on: push
jobs:
  prod-check:
    if: ${{ github.ref == 'refs/heads/main' }}
    runs-on: ubuntu-latest
    steps:
      - run: echo "Deploying to production server on branch $GITHUB_REF"

name: CI
on: push
jobs:
  prod-check:
    if: ${{ github.ref == 'refs/heads/main' }}
    runs-on: ubuntu-latest
    steps:
      - run: echo "Deploying to production server on branch $GITHUB_REF"

Dans cet exemple, l’instruction if vérifie le contexte github.ref pour déterminer le nom de la branche actuelle. Si le nom est refs/heads/main, les étapes suivantes sont exécutées. La if vérification est traitée par GitHub Actions, et le travail est envoyé uniquement à l’exécuteur si le résultat est true. Une fois le travail envoyé à l’exécuteur, l’étape est exécutée et référence la variable $GITHUB_REF de l’exécuteur.

Disponibilité du contexte

Différents contextes sont disponibles tout au long d’une exécution de workflow. Par exemple, le contexte secrets peut uniquement être utilisé à certains endroits au sein d’un travail.

De plus, certaines fonctions peuvent uniquement être utilisées à certains endroits. Par exemple, la fonction hashFiles n’est pas disponible partout.

Le tableau suivant répertorie les restrictions sur l’utilisation de chaque contexte et chaque fonction spéciale dans un workflow. Les contextes répertoriés sont disponibles uniquement pour la clé de workflow spécifiée et ne peuvent pas être utilisés ailleurs. Si elle n’est pas listée ci-dessous, une fonction peut être utilisée n’importe où.

Exemple : impression d’informations de contexte dans le journal

Vous pouvez imprimer le contenu des contextes dans le journal pour le débogage. La fonction toJSON est nécessaire pour l’impression élégante des objets JSON dans le journal.

name: Context testing
on: push

jobs:
  dump_contexts_to_log:
    runs-on: ubuntu-latest
    steps:
      - name: Dump GitHub context
        env:
          GITHUB_CONTEXT: ${{ toJson(github) }}
        run: echo "$GITHUB_CONTEXT"
      - name: Dump job context
        env:
          JOB_CONTEXT: ${{ toJson(job) }}
        run: echo "$JOB_CONTEXT"
      - name: Dump steps context
        env:
          STEPS_CONTEXT: ${{ toJson(steps) }}
        run: echo "$STEPS_CONTEXT"
      - name: Dump runner context
        env:
          RUNNER_CONTEXT: ${{ toJson(runner) }}
        run: echo "$RUNNER_CONTEXT"
      - name: Dump strategy context
        env:
          STRATEGY_CONTEXT: ${{ toJson(strategy) }}
        run: echo "$STRATEGY_CONTEXT"
      - name: Dump matrix context
        env:
          MATRIX_CONTEXT: ${{ toJson(matrix) }}
        run: echo "$MATRIX_CONTEXT"

name: Context testing
on: push

jobs:
  dump_contexts_to_log:
    runs-on: ubuntu-latest
    steps:
      - name: Dump GitHub context
        env:
          GITHUB_CONTEXT: ${{ toJson(github) }}
        run: echo "$GITHUB_CONTEXT"
      - name: Dump job context