Utilisation de l’interface CLI GitHub sur un exécuteur

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.

Présentation des exemples

Cet article utilise un exemple de workflow pour illustrer certaines des principales fonctionnalités CI de GitHub Actions. Lorsque ce workflow est déclenché, il exécute automatiquement un script qui vérifie si le site GitHub Docs a des liens brisés. Si des liens brisés sont trouvés, le workflow utilise l’interface CLI GitHub pour créer un problème GitHub avec les détails.

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

Diagramme de vue d’ensemble des étapes de workflow

Fonctionnalités utilisées dans cet exemple

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

Fonctionnalité	Implémentation
Exécution d’un workflow à intervalles réguliers :	`schedule`

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-all-english-links.yml.

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

YAML

name: Check all English links

# **What it does**: This script once a day checks all English links and reports in issues.
# **Why we have it**: We want to know if any links break.
# **Who does it impact**: Docs content.

on:
  workflow_dispatch:
  schedule:
    - cron: '40 19 * * *' # once a day at 19:40 UTC / 11:40 PST

permissions:
  contents: read
  issues: write

jobs:
  check_all_english_links:
    name: Check all links
    if: github.repository == 'github/docs-internal'
    runs-on: ubuntu-latest
    env:
      GITHUB_TOKEN: ${{ secrets.DOCUBOT_READORG_REPO_WORKFLOW_SCOPES }}
      FIRST_RESPONDER_PROJECT: Docs content first responder
      REPORT_AUTHOR: docubot
      REPORT_LABEL: broken link report
      REPORT_REPOSITORY: github/docs-content
    steps:
      - name: Check out repo's default branch
        uses: actions/checkout@v2
      - name: Setup Node
        uses: actions/setup-node@v2
        with:
          node-version: 16.13.x
          cache: npm
      - name: npm ci
        run: npm ci
      - name: npm run build
        run: npm run build
      - name: Run script
        run: |
          script/check-english-links.js > broken_links.md

      # check-english-links.js returns 0 if no links are broken, and 1 if any links
      # are broken. When an Actions step's exit code is 1, the action run's job status
      # is failure and the run ends. The following steps create an issue for the
      # broken link report only if any links are broken, so `if: ${{ failure() }}`
      # ensures the steps run despite the previous step's failure of the job.

      - if: ${{ failure() }}
        name: Get title for issue
        id: check
        run: echo "::set-output name=title::$(head -1 broken_links.md)"
      - if: ${{ failure() }}
        name: Create issue from file
        id: broken-link-report
        uses: peter-evans/create-issue-from-file@b4f9ee0a9d4abbfc6986601d9b1a4f8f8e74c77e
        with:
          token: ${{ env.GITHUB_TOKEN }}

          title: ${{ steps.check.outputs.title }}
          content-filepath: ./broken_links.md
          repository: ${{ env.REPORT_REPOSITORY }}
          labels: ${{ env.REPORT_LABEL }}
      - if: ${{ failure() }}
        name: Close and/or comment on old issues
        env:
          NEW_REPORT_URL: 'https://github.com/${{ env.REPORT_REPOSITORY }}/issues/${{ steps.broken-link-report.outputs.issue-number }}'
        run: |
          gh alias set list-reports "issue list \
                                       --repo ${{ env.REPORT_REPOSITORY }} \
                                       --author ${{ env.REPORT_AUTHOR }} \
                                       --label '${{ env.REPORT_LABEL }}'"

          # Link to the previous report from the new report that triggered this
          # workflow run.

          previous_report_url=$(gh list-reports \
                                  --state all \
                                  --limit 2 \
                                  --json url \
                                  --jq '.[].url' \
                                  | grep -v ${{ env.NEW_REPORT_URL }} | head -1)

          gh issue comment ${{ env.NEW_REPORT_URL }} --body "⬅️ [Previous report]($previous_report_url)"

          # If an old report is open and assigned to someone, link to the newer
          # report without closing the old report.

          for issue_url in $(gh list-reports \
                                  --json assignees,url \
                                  --jq '.[] | select (.assignees != []) | .url'); do
            if [ "$issue_url" != "${{ env.NEW_REPORT_URL }}" ]; then
              gh issue comment $issue_url --body "➡️ [Newer report](${{ env.NEW_REPORT_URL }})"
            fi
          done

          # Link to the newer report from any older report that is still open,
          # then close the older report and remove it from the first responder's
          # project board.

          for issue_url in $(gh list-reports \
                                  --search 'no:assignee' \
                                  --json url \
                                  --jq '.[].url'); do
            if [ "$issue_url" != "${{ env.NEW_REPORT_URL }}" ]; then
              gh issue comment $issue_url --body "➡️ [Newer report](${{ env.NEW_REPORT_URL }})"
              gh issue close $issue_url
              gh issue edit $issue_url --remove-project "${{ env.FIRST_RESPONDER_PROJECT }}"
            fi
          done

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: Check all English links`	Nom du workflow tel qu’il apparaît sous l’onglet « Actions » du dépôt GitHub.
YAML `on: workflow_dispatch: schedule: - cron: '40 20 * * *' # once a day at 20:40 UTC / 12:40 PST`	Définit les `workflow_dispatch` et `scheduled` comme déclencheurs du workflow : `workflow_dispatch` vous permet d’exécuter manuellement ce workflow à partir de l’interface utilisateur. Pour plus d’informations, consultez `workflow_dispatch`. L’événement `schedule` vous permet d’utiliser la syntaxe `cron` pour définir un intervalle régulier pour déclencher automatiquement le workflow. Pour plus d’informations, consultez `schedule`.
YAML `permissions: contents: read issues: write`	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 `jobs:`	Regroupe tous les travaux qui s’exécutent dans le fichier de workflow.
YAML `check_all_english_links: name: Check all links`	Définit un travail avec l’ID `check_all_english_links` et le nom `Check all links`, qui est stocké dans la clé `jobs`.
YAML `if: github.repository == 'github/docs-internal'`	N’exécutez le travail `check_all_english_links` que si le référentiel est nommé `docs-internal` et se trouve dans l’organisation `github`. Sinon, le travail est marqué comme étant ignoré.
YAML `runs-on: ubuntu-latest`	Configure le travail pour qu’il soit exécuté sur un exécuteur Ubuntu Linux. Cela signifie que le travail sera exécuté sur une machine virtuelle fraîche hébergée par GitHub. Pour obtenir des exemples de syntaxe utilisant d’autres exécuteurs, consultez « Workflow syntax for GitHub Actions ».
YAML `env: GITHUB_TOKEN: ${{ secrets.DOCUBOT_READORG_REPO_WORKFLOW_SCOPES }} REPORT_AUTHOR: docubot REPORT_LABEL: broken link report REPORT_REPOSITORY: github/docs-content`	Crée des variables d’environnement personnalisées et redéfinit la variable intégrée `GITHUB_TOKEN` pour utiliser un secret personnalisé. Ces variables seront référencées plus loin dans le workflow.
YAML `steps:`	Regroupe toutes les étapes qui s’exécutent dans le cadre du travail `check_all_english_links`. Chaque travail du workflow a sa propre section `steps`.
YAML `- name: Check out repo's default branch uses: actions/checkout@v2`	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 de validation chaque fois que votre workflow s’exécutera sur le code du référentiel ou que vous utilisez une action définie dans le référentiel.
YAML `- name: Setup Node uses: actions/setup-node@v2 with: node-version: 16.8.x cache: npm`	Cette étape utilise l’action `actions/setup-node` pour installer la version spécifiée du package logiciel `node` sur l’exécuteur, ce qui vous donne accès à la commande `npm`.
YAML `- name: Run the "npm ci" command run: npm ci - name: Run the "npm run build" command run: npm run build`	Le mot clé `run` indique au travail d’exécuter une commande sur l’exécuteur. Dans ce cas, les commandes `npm ci` et `npm run build` sont exécutées en tant qu’étapes distinctes pour installer et générer l’application Node.js dans le référentiel.
YAML `- name: Run script run: \| script/check-english-links.js > broken_links.md`	Cette commande `run` exécute un script qui est stocké dans le référentiel à l’emplacement `script/check-english-links.js`, et dirige la sortie vers un fichier appelé `broken_links.md`.
YAML `- if: ${{ failure() }} name: Get title for issue id: check run: echo "::set-output name=title::$(head -1 broken_links.md)"`	Si le script `check-english-links.js` détecte les liens brisés et retourne un état de sortie non nul (échec), utilisez une commande de workflow pour définir une sortie qui a la valeur de la première ligne du fichier `broken_links.md` (nous l’utiliserons à l’étape suivante).
YAML `- if: ${{ failure() }} name: Create issue from file id: broken-link-report uses: peter-evans/create-issue-from-file@b4f9ee0a9d4abbfc6986601d9b1a4f8f8e74c77e with: token: ${{ env.GITHUB_TOKEN }} title: ${{ steps.check.outputs.title }} content-filepath: ./broken_links.md repository: ${{ env.REPORT_REPOSITORY }} labels: ${{ env.REPORT_LABEL }}`	Utilise l’action `peter-evans/create-issue-from-file` pour créer un nouveau problème GitHub. Cet exemple est épinglé à une version spécifique de l’action, à l’aide du SHA `b4f9ee0a9d4abbfc6986601d9b1a4f8f8e74c77e`.
YAML - if: ${{ failure() }} name: Close and/or comment on old issues env: NEW_REPORT_URL: 'https://github.com/${{ env.REPORT_REPOSITORY }}/issues/${{ steps.broken-link-report.outputs.issue-number }}' run: \| gh alias set list-reports "issue list \ --repo ${{ env.REPORT_REPOSITORY }} \ --author ${{ env.REPORT_AUTHOR }} \ --label '${{ env.REPORT_LABEL }}'" previous_report_url=$(gh list-reports \ --state all \ --limit 2 \ --json url \ --jq '.[].url' \ \| grep -v ${{ env.NEW_REPORT_URL }} \| head -1) gh issue comment ${{ env.NEW_REPORT_URL }} --body "⬅️ [Previous report]($previous_report_url)"	Utilise `gh issue list` pour localiser le problème créé précédemment à partir d’exécutions antérieures. Il s’agit d’un alias de `gh list-reports` pour un traitement plus simple dans les étapes ultérieures. Pour obtenir l’URL du problème, l’expression `jq` traite la sortie JSON résultante. `gh issue comment` est ensuite utilisé pour ajouter un commentaire au nouveau problème qui renvoie au précédent.
YAML `for issue_url in $(gh list-reports \ --json assignees,url \ --jq '.[] \| select (.assignees != []) \| .url'); do if [ "$issue_url" != "$" ]; then gh issue comment $issue_url --body "➡️ [Newer report]($)" fi done`	Si un problème d’une exécution précédente est ouvert et affecté à une personne, utilisez `gh issue comment` pour ajouter un commentaire avec un lien vers le nouveau problème.
YAML `for issue_url in $(gh list-reports \ --search 'no:assignee' \ --json url \ --jq '.[].url'); do if [ "$issue_url" != "${{ env.NEW_REPORT_URL }}" ]; then gh issue comment $issue_url --body "➡️ [Newer report](${{ env.NEW_REPORT_URL }})" gh issue close $issue_url gh issue edit $issue_url --remove-project "${{ env.FIRST_RESPONDER_PROJECT }}" fi done`	Si un problème d’une exécution précédente est ouvert et n’est attribué à personne, alors : Utilisez `gh issue comment` pour ajouter un commentaire avec un lien vers le nouveau problème. Utilisez `gh issue close` pour fermer l’ancien problème. Utilisez `gh issue edit` pour modifier l’ancien problème afin de le supprimer d’un tableau de projet spécifique GitHub.

Étapes suivantes

Pour découvrir les concepts de GitHub Actions, consultez « 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. ».
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.