Authentification par jeton automatique

À propos du secret GITHUB_TOKEN

Au début de chaque travail de workflow, GitHub crée automatiquement un secret GITHUB_TOKEN unique à utiliser dans votre workflow. Vous pouvez utiliser GITHUB_TOKEN pour vous authentifier dans un travail de workflow.

Lorsque vous activez GitHub Actions, GitHub installe une GitHub App sur votre dépôt. Le secret GITHUB_TOKEN est un jeton d’accès d’installation GitHub App. Vous pouvez utiliser le jeton d’accès d’installation pour vous authentifier au nom de GitHub App installée sur votre dépôt. Les autorisations du jeton sont limitées au dépôt qui contient votre workflow. Pour plus d’informations, consultez « Autorisations pour le GITHUB_TOKEN ».

Avant que chaque travail ne commence, GitHub récupère un jeton d’accès d’installation pour le travail. Le GITHUB_TOKEN expire à la fin d’un travail ou après un délai maximal de 24 heures.

Le jeton est également disponible dans le contexte github.token. Pour plus d’informations, consultez « Accès à des informations contextuelles sur l’exécution d’un workflow ».

Utilisation de GITHUB_TOKEN dans un workflow

Vous pouvez utiliser le GITHUB_TOKEN avec la syntaxe standard pour référencer les secrets : ${{ secrets.GITHUB_TOKEN }}. Des exemples d’utilisation du GITHUB_TOKEN incluent la transmission du jeton en tant qu’entrée pour une action ou son utilisation pour créer une demande d’API GitHub authentifiée.

Lorsque vous utilisez le GITHUB_TOKEN du dépôt pour effectuer des tâches, les événements déclenchés par le GITHUB_TOKEN, avec l’exception de workflow_dispatch et de repository_dispatch, ne créent pas de nouvelle exécution de workflow. Cela vous empêche de créer accidentellement des exécutions de workflow récursives. Par exemple, si une exécution de workflow pousse (push) du code à l’aide du GITHUB_TOKEN du dépôt, aucun nouveau workflow ne s’exécute même quand le dépôt contient un workflow configuré pour s’exécuter quand des événements push se produisent.

Les commits envoyés par un workflow GitHub Actions qui utilise le GITHUB_TOKEN ne déclenchent pas de build GitHub Pages.

Exemple 1 : passage du GITHUB_TOKEN en tant qu’entrée

Cet exemple de flux de travail utilise leCLI GitHub, qui nécessite GITHUB_TOKEN en tant que valeur du paramètre d’entrée de GH_TOKEN :

name: Open new issue
on: workflow_dispatch

jobs:
  open-issue:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      issues: write
    steps:
      - run: |
          gh issue --repo ${{ github.repository }} \
            create --title "Issue title" --body "Issue body"
        env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}

name: Open new issue
on: workflow_dispatch

jobs:
  open-issue:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      issues: write
    steps:
      - run: |
          gh issue --repo ${{ github.repository }} \
            create --title "Issue title" --body "Issue body"
        env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}

Exemple 2 : appel de l’API REST

Vous pouvez utiliser le GITHUB_TOKEN pour effectuer des appels d’API authentifiés. Cet exemple de workflow crée un problème à l’aide de l’API REST GitHub :

name: Create issue on commit

on: [ push ]

jobs:
  create_issue:
    runs-on: ubuntu-latest
    permissions:
      issues: write
    steps:
      - name: Create issue using REST API
        run: |
          curl --request POST \
          --url https://api.github.com/repos/${{ github.repository }}/issues \
          --header 'authorization: Bearer ${{ secrets.GITHUB_TOKEN }}' \
          --header 'content-type: application/json' \
          --data '{
            "title": "Automated issue for commit: ${{ github.sha }}",
            "body": "This issue was automatically created by the GitHub Action workflow **${{ github.workflow }}**. \n\n The commit hash was: _${{ github.sha }}_."
            }' \
          --fail

Autorisations pour le GITHUB_TOKEN

Pour plus d’informations sur les points de terminaison d’API auxquels GitHub Apps peut accéder avec chaque autorisation, consultez « Autorisations requises pour les applications GitHub ».

Le tableau suivant montre les autorisations octroyées à GITHUB_TOKEN par défaut. Les personnes disposant d’autorisations d’administrateur sur une entreprise, une organisation ou un dépôt, peuvent définir les autorisations par défaut comme étant permissives ou restreintes. Pour plus d’informations sur la définition des autorisations par défaut pour le GITHUB_TOKEN de votre entreprise, organisation ou dépôt, consultez « Application de stratégies pour GitHub Actions dans votre entreprise », « Désactivation ou limitation de la fonctionnalité GitHub Actions pour votre organisation » ou « Gestion des paramètres de GitHub Actions pour un dépôt ».

Modification des autorisations pour GITHUB_TOKEN

Vous pouvez modifier les autorisations pour GITHUB_TOKEN dans des fichiers de workflow individuels. Si les autorisations par défaut pour le GITHUB_TOKEN sont restrictives, vous devrez peut-être élever les autorisations pour permettre l’exécution de certaines actions et commandes. Si les autorisations par défaut sont permissives, vous pouvez modifier le fichier de workflow pour supprimer des autorisations du GITHUB_TOKEN. En guise de bonne pratique de sécurité, vous devez accorder à GITHUB_TOKEN le moins d’accès requis.

Vous pouvez voir les autorisations dont disposait GITHUB_TOKEN pour un travail spécifique dans la section « Configurer un travail » du journal d’exécution de workflow. Pour plus d’informations, consultez « Using workflow run logs ».

Vous pouvez utiliser la clé permissions dans votre fichier de workflow pour modifier les autorisations du GITHUB_TOKEN pour un workflow entier ou pour des travaux individuels. Cela vous permet de configurer les autorisations minimales requises pour un workflow ou un travail. Lorsque la clé permissions est utilisée, toutes les autorisations non spécifiées sont définies sur Aucun accès, à l’exception de l’étendue metadata, qui obtient toujours l’accès en lecture.

Vous pouvez utiliser la clé permissions afin d’ajouter et de supprimer des autorisations d’accès en lecture pour les dépôts dupliqués. Toutefois, en règle générale, vous ne pouvez pas octroyer d’accès en écriture. Il existe une exception à ce comportement. Il s’agit du moment où un utilisateur administrateur a sélectionné l’option Envoyer des jetons d’écriture aux workflows à partir des demandes de tirage dans les paramètres de GitHub Actions. Pour plus d’informations, consultez « Gestion des paramètres de GitHub Actions pour un dépôt ».

Les deux exemples de workflow précédents dans cet article montrent la clé permissions utilisée au niveau du travail, car il est recommandé de limiter l’étendue des autorisations.

Pour plus d’informations sur la clé permissions, consultez « Workflow syntax for GitHub Actions ».

Calcul des autorisations pour un travail de workflow

Les autorisations pour le GITHUB_TOKEN sont initialement définies sur le paramètre par défaut pour l’entreprise, l’organisation ou le dépôt. Si la valeur par défaut est définie sur les autorisations restreintes à l’un de ces niveaux, cela s’applique aux dépôts appropriés. Par exemple, si vous choisissez la valeur par défaut restreinte au niveau de l’organisation, tous les dépôts de cette organisation utiliseront les autorisations restreintes comme valeur par défaut. Les autorisations sont ensuite ajustées en fonction de n’importe quelle configuration dans le fichier de workflow, d’abord au niveau du workflow, puis au niveau du travail. Enfin, si le workflow a été déclenché par une demande de tirage à partir d’un dépôt dupliqué et que le paramètre Envoyer des jetons d’écriture aux workflows à partir des demandes de tirage n’est pas sélectionné, les autorisations sont ajustées pour remplacer les autorisations d’écriture par lecture seule.

Octroi d’autorisations supplémentaires

Si vous avez besoin d’un jeton qui nécessite des autorisations non disponibles dans GITHUB_TOKEN, vous pouvez créer une GitHub App et générer un jeton d’accès d’installation dans votre workflow. Pour plus d’informations, consultez « Effectuer des requêtes d’API authentifiées avec une application GitHub dans un workflow GitHub Actions ». Vous pouvez également créer un personal access token, le stocker en tant que secret dans votre référentiel et utiliser le jeton dans votre workflow avec la syntaxe ${{ secrets.SECRET_NAME }}. Pour plus d’informations, consultez « Gestion de vos jetons d'accès personnels » et « Utilisation de secrets dans GitHub Actions ».

Pour aller plus loin

• Limites de débit pour l'API REST