Utilisation de secrets dans GitHub Actions

À propos des secrets

Les secrets sont des variables que vous créez dans une organisation, un dépôt ou un environnement de dépôt. Les secrets que vous créez sont disponibles pour être utilisés dans les workflows GitHub Actions. GitHub Actions peut lire un secret uniquement si vous l’incluez explicitement dans un workflow.

Pour les secrets stockés au niveau de l’organisation, vous pouvez utiliser des stratégies d’accès pour contrôler les référentiels pouvant utiliser les secrets de l’organisation. Les secrets au niveau de l’organisation vous permettent de partager des secrets entre plusieurs référentiels, ce qui réduit la nécessité de créer des secrets en double. La mise à jour d’un secret d’organisation dans un emplacement garantit également que la modification prend effet dans tous les workflows de référentiel qui utilisent ce secret.

Pour les secrets stockés au niveau de l’environnement, vous pouvez permettre aux réviseurs nécessaires de contrôler l’accès aux secrets. Un travail de workflow ne peut pas accéder aux secrets d’environnement tant que l’approbation n’est pas accordée par les réviseurs nécessaires.

Nommage de vos secrets

Les règles suivantes s’appliquent aux noms de secrets :

• Les noms peuvent contenir uniquement des caractères alphanumériques ([a-z], [A-Z], [0-9]) ou des traits de soulignement (_). Les espaces ne sont pas autorisés.

• Les noms ne doivent pas commencer par le préfixe GITHUB_.

• Les noms ne doivent pas commencer par un chiffre.

• Les noms ne respectent pas la casse.

• Les noms doivent être uniques au niveau où ils sont créés.

  Par exemple, un secret créé au niveau de l’environnement doit avoir un nom unique dans cet environnement, un secret créé au niveau du dépôt doit avoir un nom unique dans ce dépôt, et un secret créé au niveau de l’organisation doit avoir un nom unique à ce niveau.

  S’il existe un secret du même nom à plusieurs niveaux, le secret au niveau le plus bas est prioritaire. Par exemple, si un secret au niveau de l’organisation porte le même nom qu’un secret au niveau du dépôt, celui-ci est prioritaire. De même, si une organisation, un dépôt et un environnement ont tous un secret portant le même nom, le secret au niveau de l’environnement est prioritaire.

Pour vous assurer que GitHub retire votre secret dans les journaux, évitez d’utiliser des données structurées comme valeurs de secrets. Par exemple, évitez de créer des secrets qui contiennent des objets blob JSON ou Git encodés.

Accès à vos secrets

Pour rendre un secret disponible pour une action, vous devez définir le secret en tant que variable d’entrée ou d’environnement dans le fichier de workflow. Passez en revue le fichier README de l’action pour en savoir plus sur les entrées et variables d’environnement attendues par l’action. Pour plus d’informations, consultez « Workflow syntax for GitHub Actions ».

Vous pouvez utiliser et lire des secrets dans un fichier de flux de travail si vous pouvez modifier le fichier. Pour plus d’informations, consultez « Autorisations d’accès sur GitHub ».

Les secrets de l’organisation et du dépôt sont lus quand une exécution de workflow est mise en file d’attente, et les secrets de l’environnement sont lus quand un travail référençant l’environnement démarre.

Vous pouvez également gérer des secrets à l’aide de l’API REST. Pour plus d’informations, consultez « Points de terminaison REST pour l’API secrets GitHub Actions ».

Limitation des autorisations d’informations d’identification

Lors de la génération d’informations d’identification, nous vous recommandons d’accorder les autorisations minimales possibles. Par exemple, au lieu d’utiliser des informations d’identification personnelles, utilisez des clés de déploiement ou un compte de service. Envisagez d’accorder des autorisations en lecture seule si cela suffit et limitez l’accès autant que possible.

Lors de la génération d’un personal access token (classic), sélectionnez aussi peu d’étendues que nécessaire. Lors de la génération d’un fine-grained personal access token, sélectionnez les autorisations et l’accès au dépôt minimaux requis.

Au lieu d’utiliser un personal access token, envisagez d’utiliser une GitHub App, qui utilise des autorisations affinées et des jetons de courte durée, comme un fine-grained personal access token. Contrairement à un personal access token, une GitHub App n’est pas liée à un utilisateur ; ainsi, le workflow continue de fonctionner même si l’utilisateur qui a installé l’application quitte votre organisation. Pour plus d’informations, consultez « Effectuer des requêtes d’API authentifiées avec une application GitHub dans un workflow GitHub Actions ».

Création de secrets pour un dépôt

Pour créer des secrets ou des variables sur GitHub pour un référentiel de compte personnel, vous devez être le propriétaire du référentiel. Pour créer des secrets ou des variables sur GitHub pour un référentiel d’une organisation, vous devez disposer d’un accès admin. Enfin, pour créer des secrets ou des variables pour un référentiel de compte personnel ou un référentiel d’organisation via l’API REST, vous devez disposer d’un accès collaborateur.

gh secret set SECRET_NAME

gh secret set SECRET_NAME < secret.txt

Création de secrets pour un environnement

Pour créer des secrets pour un environnement dans un référentiel de compte personnel, vous devez être le propriétaire du référentiel. Pour créer des secrets ou des variables pour un environnement dans un référentiel d’organisation, vous devez disposer d’un accès admin. Pour plus d’informations sur les environnements, consultez « Gestion des environnements pour le déploiement ».

gh secret set --env ENV_NAME SECRET_NAME

gh secret list --env ENV_NAME

Création de secrets pour une organisation

Quand vous créez un secret ou une variable dans une organisation, vous pouvez utiliser une stratégie pour limiter l’accès par dépôt. Par exemple, vous pouvez accorder l’accès à tous les dépôts, ou limiter l’accès aux seuls dépôts privés ou à une liste spécifiée de dépôts.

Les propriétaires d’organisations et les utilisateurs disposant des autorisations « Gérer les variables d’action de l’organisation » ou « Gérer les secrets d’action d’organisation » peuvent créer des secrets ou des variables au niveau de l’organisation.

Pour plus d’informations, consultez « À propos des rôles d'organisation personnalisés ».

gh auth login --scopes "admin:org"

gh secret set --org ORG_NAME SECRET_NAME

gh secret set --org ORG_NAME SECRET_NAME --visibility all

gh secret set --org ORG_NAME SECRET_NAME --repos REPO-NAME-1, REPO-NAME-2

gh secret list --org ORG_NAME

Examen de l’accès aux secrets au niveau de l’organisation

Vous pouvez vérifier quelles stratégies d’accès sont appliquées à un secret dans votre organisation.

1. Sur GitHub, accédez à la page principale de l’organisation.

2. Sous le nom de votre organisation, cliquez sur Paramètres. Si vous ne voyez pas l’onglet « Paramètres », sélectionnez le menu déroulant , puis cliquez sur Paramètres.

   

3. Dans la section Sécurité de la barre latérale, sélectionnez Secrets et variables, puis cliquez sur Actions.

4. La liste des secrets inclut toutes les autorisations et stratégies configurées. Pour plus d’informations sur les autorisations configurées pour chaque secret, cliquez sur Mettre à jour.

Utilisation de secrets dans un flux de travail

Pour fournir une action avec un secret en tant que variable d’entrée ou d’environnement, vous pouvez utiliser le contexte secrets pour accéder aux secrets que vous avez créés dans votre dépôt. Pour plus d’informations, consultez « Accès à des informations contextuelles sur l’exécution d’un workflow » et « Workflow syntax for GitHub Actions ».

steps:
  - name: Hello world action
    with: # Set the secret as an input
      super_secret: ${{ secrets.SuperSecret }}
    env: # Or as an environment variable
      super_secret: ${{ secrets.SuperSecret }}

Les secrets ne peuvent pas être directement référencés dans les conditions if:. Au lieu de cela, envisagez de définir des secrets en tant que variables d’environnement au niveau du travail, puis de référencer les variables d’environnement pour exécuter des étapes de manière conditionnelle dans le travail. Pour plus d’informations, consultez « Accès à des informations contextuelles sur l’exécution d’un workflow » et jobs.<job_id>.steps[*].if.

Si un secret n’a pas été défini, la valeur de retour d’une expression référençant le secret (comme ${{ secrets.SuperSecret }} dans l’exemple) est une chaîne vide.

Évitez de passer des secrets entre les processus de la ligne de commande, dans la mesure du possible. Les processus de ligne de commande peuvent être visibles par d’autres utilisateurs (à l’aide de la commande ps) ou capturés par des événements d’audit de sécurité. Pour protéger les secrets, envisagez d’utiliser des variables d’environnement, STDIN ou d’autres mécanismes pris en charge par le processus cible.

Si vous devez passer des secrets dans une ligne de commande, placez-les entre guillemets conformément aux règles appropriées. Les secrets contiennent souvent des caractères spéciaux susceptibles d’affecter involontairement votre environnement. Pour placer ces caractères spéciaux dans une séquence d’échappement, utilisez des guillemets avec vos variables d’environnement. Par exemple :

Exemple d’utilisation de Bash

steps:
  - shell: bash
    env:
      SUPER_SECRET: ${{ secrets.SuperSecret }}
    run: |
      example-command "$SUPER_SECRET"

Exemple d’utilisation de PowerShell

steps:
  - shell: pwsh
    env:
      SUPER_SECRET: ${{ secrets.SuperSecret }}
    run: |
      example-command "$env:SUPER_SECRET"

Exemple d’utilisation de Cmd.exe

steps:
  - shell: cmd
    env:
      SUPER_SECRET: ${{ secrets.SuperSecret }}
    run: |
      example-command "%SUPER_SECRET%"

Limites pour les secrets

Vous pouvez stocker jusqu’à 1 000 secrets d’organisation, 100 secrets de dépôt et 100 secrets d’environnement.

Un workflow créé dans un dépôt peut accéder au nombre de secrets suivant :

• Les 100 secrets du dépôt.
• Si le dépôt a accès à plus de 100 secrets d’organisation, le workflow ne peut utiliser que les 100 premiers secrets d’organisation (triés par ordre alphabétique par nom de secret).
• Les 100 secrets d’environnement.

La taille des secrets est limitée à 48 ko. Pour stocker des secrets plus volumineux, consultez la solution de contournement « Stockage de secrets volumineux » ci-dessous.

Stockage de secrets volumineux

Pour utiliser des secrets avec une taille supérieure à 48 Ko, vous pouvez utiliser une solution de contournement pour stocker les secrets dans votre référentiel et enregistrer la phrase secrète de déchiffrement sous la forme d’un secret sur GitHub. Par exemple, vous pouvez utiliser gpg pour chiffrer un fichier contenant votre secret localement avant de vérifier le fichier chiffré dans votre référentiel sur GitHub. Pour plus d’informations, consultez « gpg manpage ».

1. Exécutez la commande suivante à partir de votre terminal pour chiffrer le fichier contenant votre secret avec gpg et l’algorithme de chiffrement AES256. Dans cet exemple, my_secret.json est le fichier contenant le secret.

   gpg --symmetric --cipher-algo AES256 my_secret.json
   

2. Vous serez invité à entrer une phrase secrète. Mémorisez la phrase secrète, car vous devrez créer un secret sur GitHub qui utilise la phrase secrète comme valeur.

3. Créez un secret qui contient la phrase secrète. Par exemple, créez un secret avec le nom LARGE_SECRET_PASSPHRASE et définissez la valeur du secret sur la phrase secrète utilisée à l’étape ci-dessus.

4. Copiez votre fichier chiffré sur un chemin d’accès dans votre référentiel et validez-le. Dans cet exemple, le fichier chiffré est my_secret.json.gpg.

   Avertissement : veillez à copier le fichier chiffré my_secret.json.gpg se terminant par l’extension de fichier .gpg et non le fichier non chiffré my_secret.json.

   git add my_secret.json.gpg
   git commit -m "Add new secret JSON file"
   

5. Créez un script d’interpréteur de commandes dans votre référentiel pour déchiffrer le fichier secret. Dans cet exemple, le script est nommé decrypt_secret.sh.

   Shell

   #!/bin/sh
   
   # Decrypt the file
   mkdir $HOME/secrets
   # --batch to prevent interactive command
   # --yes to assume "yes" for questions
   gpg --quiet --batch --yes --decrypt --passphrase="$LARGE_SECRET_PASSPHRASE" \
   --output $HOME/secrets/my_secret.json my_secret.json.gpg
   

6. Vérifiez que votre script shell est exécutable avant de l’archiver dans votre dépôt.

   chmod +x decrypt_secret.sh
   git add decrypt_secret.sh
   git commit -m "Add new decryption script"
   git push
   

7. Dans votre workflow GitHub Actions, utilisez un step pour appeler le script d’interpréteur de commandes et déchiffrer le secret. Pour avoir une copie de votre dépôt dans l’environnement dans lequel votre workflow s’exécute, vous devez utiliser l’action actions/checkout. Référencez votre script shell à l’aide de la commande run relative à la racine de votre dépôt.

   name: Workflows with large secrets
   
   on: push
   
   jobs:
     my-job:
       name: My Job
       runs-on: ubuntu-latest
       steps:
         - uses: actions/checkout@v4
         - name: Decrypt large secret
           run: ./decrypt_secret.sh
           env:
             LARGE_SECRET_PASSPHRASE: ${{ secrets.LARGE_SECRET_PASSPHRASE }}
         # This command is just an example to show your secret being printed
         # Ensure you remove any print statements of your secrets. GitHub does
         # not hide secrets that use this workaround.
         - name: Test printing your secret (Remove this step in production)
           run: cat $HOME/secrets/my_secret.json
   

Stockage d’objets blob binaires Base64 en tant que secrets

Vous pouvez utiliser l’encodage Base64 pour stocker de petits objets blob binaires en tant que secrets. Vous pouvez ensuite référencer le secret dans votre workflow et le décoder pour une utilisation sur l’exécuteur. Pour connaître les limites de taille, consultez « Utilisation de secrets dans GitHub Actions ».

1. Utilisez base64 pour encoder votre fichier en une chaîne Base64. Par exemple :

   Sur macOS, vous pouvez exécuter :

   base64 -i cert.der -o cert.base64
   

   Sur Linux, vous pouvez exécuter :

   base64 -w 0 cert.der > cert.base64
   

2. Créez un secret qui contient la chaîne Base64. Par exemple :

   $ gh secret set CERTIFICATE_BASE64 < cert.base64
   ✓ Set secret CERTIFICATE_BASE64 for octocat/octorepo
   

3. Pour accéder à la chaîne Base64 à partir de votre exécuteur, dirigez le secret vers base64 --decode. Par exemple :

   name: Retrieve Base64 secret
   on:
     push:
       branches: [ octo-branch ]
   jobs:
     decode-secret:
       runs-on: ubuntu-latest
       steps:
         - uses: actions/checkout@v4
         - name: Retrieve the secret and decode it to a file
           env:
             CERTIFICATE_BASE64: ${{ secrets.CERTIFICATE_BASE64 }}
           run: |
             echo $CERTIFICATE_BASE64 | base64 --decode > cert.der
         - name: Show certificate information
           run: |
             openssl x509 -in cert.der -inform DER -text -noout
   

Retrait des secrets à partir des journaux d’exécution de workflow

GitHub Actions masque automatiquement le contenu de tous les secrets GitHub imprimés dans les journaux de flux de travail.

GitHub Actions masque également les informations qui sont reconnues comme sensibles, mais qui ne sont pas stockées en tant que secret. Actuellement, GitHub prend en charge :

• Clés Azure 32 octets et 64 octets
• Mots de passe d’application cliente Azure AD
• Clés du cache Azure
• Clés Azure Container Registry
• Clés d’hôte Azure Functions
• Clés Recherche Azure
• Chaînes de connexion de base de données
• En-têtes de jeton du porteur HTTP
• JWT
• Jetons d’auteur NPM
• Clés d’API NuGet
• Jetons d’installation GitHub v1
• Jetons d’installation GitHub v2 (ghp, gho, ghu, ghs, ghr)
• PAT GitHub v2

En guise de bonne pratique, vous devez masquer toutes les informations sensibles qui ne sont pas des secrets GitHub en utilisant ::add-mask::VALUE. Cela entraîne le traitement de la valeur en tant que secret, qui est alors masquée dans les journaux. Pour plus d’informations sur comment masquer les données, consultez « Workflow commands for GitHub Actions ».

Vos exécuteurs de flux de travail se chargent de masquer les secrets. Cela signifie qu’un secret sera retiré uniquement s’il a été utilisé dans un projet et est accessible par l’exécuteur. Si un secret non masqué est envoyé à un journal d’exécution de flux de travail, vous devez supprimer le journal et faire pivoter le secret. Pour plus d’informations sur la suppression des journaux, consultez « Using workflow run logs ».