Authentification par jeton automatique

À propos du secret _TOKEN

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

Lorsque vous activez Actions, installe une App sur votre dépôt. Le secret _TOKEN est un jeton d’accès d’installation App. Vous pouvez utiliser le jeton d’accès d’installation pour vous authentifier au nom de 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 _TOKEN ».

Avant que chaque travail ne commence, récupère un jeton d’accès d’installation pour le travail. Le _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 .token. Pour plus d’informations, consultez « Accès à des informations contextuelles sur l’exécution d’un workflow ».

Utilisation de _TOKEN dans un workflow

Vous pouvez utiliser le _TOKEN avec la syntaxe standard pour référencer les secrets : ${{ secrets._TOKEN }}. Les exemples d'utilisation _TOKEN du jeton incluent le passage du jeton en tant qu'entrée d'une action, ou son utilisation pour effectuer une requête API authentifiée. demande d'API authentifiée.

Lorsque vous utilisez le _TOKEN du référentiel pour effectuer des tâches, les événements déclenchés par le _TOKEN, à l’exception du workflow_dis et du repository_dis, ne créeront pas une nouvelle exécution du flux de travail. 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 _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 Actions qui utilise le _TOKEN ne déclenchent pas de build Pages.

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

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

name: Open new issue
on: workflow_dis

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

name: Open new issue
on: workflow_dis

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

Exemple 2 : appel de l’API REST

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

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..com/repos/${{ .repository }}/issues \
          --header 'authorization: Bearer ${{ secrets._TOKEN }}' \
          --header 'content-type: application/json' \
          --data '{
            "title": "Automated issue for commit: ${{ .sha }}",
            "body": "This issue was automatically created by the  Action workflow **${{ .workflow }}**. \n\n The commit hash was: _${{ .sha }}_."
            }' \
          --fail

Autorisations pour le _TOKEN

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

Le tableau suivant montre les autorisations octroyées à _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 _TOKEN de votre entreprise, organisation ou dépôt, consultez « Application de stratégies pour Actions dans votre entreprise », « Désactivation ou limitation de la fonctionnalité Actions pour votre organisation » ou « Gestion des paramètres de Actions pour un dépôt ».

Modification des autorisations pour _TOKEN

Vous pouvez modifier les autorisations pour _TOKEN dans des fichiers de workflow individuels. Si les autorisations par défaut pour le _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 _TOKEN. En guise de bonne pratique de sécurité, vous devez accorder à _TOKEN le moins d’accès requis.

Vous pouvez voir les autorisations dont disposait _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 _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.

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 Actions. Pour plus d’informations, consultez « Gestion des paramètres de 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 Actions ».

Calcul des autorisations pour un travail de workflow

Les autorisations pour le _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 _TOKEN, vous pouvez créer une 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 dans un workflow 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 Actions ».

Pour aller plus loin

• Limites de débit pour l'API REST