Utilisation de scripts pour tester votre code sur un exécuteur

Présentation des exemples

Cet article utilise un exemple de workflow pour illustrer certaines des principales fonctionnalités CI de GitHub Actions. Quand ce workflow est déclenché, il exécute automatiquement un script qui vérifie si le site GitHub Docs comporte des liens rompus.

Le diagramme suivant montre une vue générale des étapes du workflow et comment elles s’exécutent dans le travail :

Schéma d’un événement déclenchant un workflow qui utilise des scripts pour tester du code.

Fonctionnalités utilisées dans cet exemple

L’exemple de workflow illustre les fonctionnalités suivantes de GitHub Actions.

Fonctionnalité	Implémentation
Déclenchement de l’exécution automatique d’un workflow :	`push`

Exemple de flux de travail

Le workflow suivant a été créé par l’équipe Ingénierie de documents GitHub. Pour consulter la dernière version de ce fichier dans le référentiel github/docs, consultez check-broken-links-github-github.yml.

Remarque : Chaque ligne de ce workflow est expliquée dans la section suivante, dans « Comprendre l’exemple ».

YAML

name: 'Link Checker: All English'

# **What it does**: Renders the content of every page and check all internal links.
# **Why we have it**: To make sure all links connect correctly.
# **Who does it impact**: Docs content.

on:
  workflow_dispatch:
  push:
    branches:
      - main
  pull_request:

permissions:
  contents: read
  # Needed for the 'trilom/file-changes-action' action
  pull-requests: read

# This allows a subsequently queued workflow run to interrupt previous runs
concurrency:
  group: '${{ github.workflow }} @ ${{ github.event.pull_request.head.label || github.head_ref || github.ref }}'
  cancel-in-progress: true

jobs:
  check-links:
    runs-on: ${{ fromJSON('["ubuntu-latest", "self-hosted"]')[github.repository == 'github/docs-internal'] }}
    steps:
      - name: Checkout
        uses: actions/checkout@v3

      - name: Setup node
        uses: actions/setup-node@v3
        with:
          node-version: 16.13.x
          cache: npm

      - name: Install
        run: npm ci

      # Creates file "$/files.json", among others
      - name: Gather files changed
        uses: trilom/file-changes-action@a6ca26c14274c33b15e6499323aac178af06ad4b
        with:
          fileOutput: 'json'

      # For verification
      - name: Show files changed
        run: cat $HOME/files.json

      - name: Link check (warnings, changed files)
        run: |
          ./script/rendered-content-link-checker.mjs \
            --language en \
            --max 100 \
            --check-anchors \
            --check-images \
            --verbose \
            --list $HOME/files.json

      - name: Link check (critical, all files)
        run: |
          ./script/rendered-content-link-checker.mjs \
            --language en \
            --exit \
            --verbose \
            --check-images \
            --level critical

Vue d’ensemble de l’exemple

Le tableau suivant explique comment chacune de ces fonctionnalités est utilisée lors de la création d’un workflow GitHub Actions.

Code	Explication
YAML `name: 'Link Checker: All English'`	Nom du workflow tel qu’il apparaît sous l’onglet « Actions » du dépôt GitHub.
YAML `on:`	Le mot clé `on` vous permet de définir les événements qui se déclenchent quand le workflow s’exécute. Vous pouvez définir ici plusieurs événements. Pour plus d’informations, consultez « Déclenchement d’un workflow ».
YAML `workflow_dispatch:`	Ajoutez l’événement `workflow_dispatch` si vous souhaitez pouvoir exécuter manuellement ce workflow à partir de l’IU. Pour plus d’informations, consultez `workflow_dispatch`.
YAML `push: branches: - main`	Ajoutez l’événement `push` pour que le workflow s’exécute automatiquement chaque fois qu’un commit est poussé vers une branche appelée `main`. Pour plus d’informations, consultez `push`.
YAML `pull_request:`	Ajoutez l’événement `pull_request` pour que le workflow s’exécute automatiquement chaque fois qu’une demande de tirage est créée ou mise à jour. Pour plus d’informations, consultez `pull_request`.
YAML `permissions: contents: read pull-requests: read`	Modifie les autorisations par défaut octroyées à `GITHUB_TOKEN`. Cela varie en fonction des besoins de votre workflow. Pour plus d’informations, consultez « Affectation d’autorisations à des travaux ».
YAML `concurrency: group: '${{ github.workflow }} @ ${{ github.event.pull_request.head.label \|\| github.head_ref \|\| github.ref }}'`	Crée un groupe d’accès concurrentiel pour des événements spécifiques, et utilise l’opérateur `\|\|` afin de définir les valeurs de secours. Pour plus d’informations, consultez « Utilisation de l’accès concurrentiel ».
YAML `cancel-in-progress: true`	Annule tout travail ou workflow en cours d’exécution dans le même groupe d’accès concurrentiel.
YAML `jobs:`	Regroupe tous les travaux qui s’exécutent dans le fichier de workflow.
YAML `check-links:`	Définit un travail ayant l’ID `check-links` stocké dans la clé `jobs`.
YAML `runs-on: ${{ fromJSON('["ubuntu-latest", "self-hosted"]')[github.repository == 'github/docs-internal'] }}`	Configure le travail pour qu’il s’exécute sur un exécuteur hébergé par GitHub ou sur un exécuteur autohébergé, selon le dépôt qui exécute le workflow. Dans cet exemple, le travail s’exécute sur un exécuteur autohébergé si le dépôt se nomme `docs-internal`, et s’il se trouve dans l’organisation `github`. Si le dépôt ne correspond pas à ce chemin, il s’exécute sur un exécuteur `ubuntu-latest` hébergé par GitHub. Pour plus d’informations sur ces options, consultez « Choix de l’exécuteur pour un travail ».
YAML `steps:`	Regroupe toutes les étapes qui vont s’exécuter dans le cadre du travail `check-links`. Chaque travail d’un workflow a sa propre section `steps`.
YAML `- name: Checkout uses: actions/checkout@v3`	Le mot clé `uses` indique au travail de récupérer l’action nommée `actions/checkout`. Il s’agit d’une action qui extrait votre dépôt et le télécharge dans l’exécuteur, ce qui vous permet d’exécuter des actions sur votre code (par exemple des outils de test). Vous devez utiliser l’action d’extraction chaque fois que votre workflow s’exécute sur le code du dépôt, ou que vous utilisez une action définie dans le dépôt.
YAML `- name: Setup node uses: actions/setup-node@v3 with: node-version: 16.13.x cache: npm`	Cette étape utilise l’action `actions/setup-node` pour installer la version spécifiée du package logiciel Node.js sur l’exécuteur, ce qui vous permet d’accéder à la commande `npm`.
YAML `- name: Install run: npm ci`	Le mot clé `run` indique au travail d’exécuter une commande sur l’exécuteur. Dans le cas présent, `npm ci` est utilisé pour installer les packages logiciels npm du projet.
YAML `- name: Gather files changed uses: trilom/file-changes-action@a6ca26c14274c33b15e6499323aac178af06ad4b with: fileOutput: 'json'`	Utilise l’action `trilom/file-changes-action` pour regrouper tous les fichiers changés. Cet exemple est épinglé à une version spécifique de l’action, à l’aide de la valeur SHA `a6ca26c14274c33b15e6499323aac178af06ad4b`.
YAML `- name: Show files changed run: cat $HOME/files.json`	Liste le contenu de `files.json`. Il est visible dans le journal de l’exécution de workflow et peut être utile pour le débogage.
YAML `- name: Link check (warnings, changed files) run: \| ./script/rendered-content-link-checker.mjs \ --language en \ --max 100 \ --check-anchors \ --check-images \ --verbose \ --list $HOME/files.json`	Cette étape utilise la commande `run` pour exécuter un script stocké dans le dépôt sur `script/rendered-content-link-checker.mjs`, puis passe tous les paramètres nécessaires à l’exécution.
YAML `- name: Link check (critical, all files) run: \| ./script/rendered-content-link-checker.mjs \ --language en \ --exit \ --verbose \ --check-images \ --level critical`	Cette étape utilise également la commande `run` pour exécuter un script stocké dans le dépôt sur `script/rendered-content-link-checker.mjs`, puis passe un autre ensemble de paramètres.

Étapes suivantes

Pour découvrir les concepts de GitHub Actions, consultez « Comprendre GitHub Actions ».
Pour un guide plus détaillé sur la création d’un workflow de base, consultez Démarrage rapide pour GitHub Actions.
Si vous êtes à l’aise avec les bases de GitHub Actions, vous pouvez vous renseigner sur les workflows et leurs caractéristiques dans À propos des workflows.