Environnements GitHub Actions : cibler un déploiement

Un environnement GitHub est une cible de déploiement nommée : staging, production, preprod. Il porte ses propres secrets, ses propres variables, ses règles de protection, et il transforme un job ordinaire en déploiement tracé dans l'onglet Deployments du dépôt. Cette page montre comment le créer, comment un job s'y rattache, et pourquoi l'isolation des secrets par environnement vaut mieux que des secrets de dépôt préfixés PROD_.

Ce que vous allez apprendre

• Créer un environnement et comprendre les contraintes sur son nom
• Rattacher un job à un environnement, dans la forme courte et la forme longue
• Publier l'URL de déploiement et savoir où GitHub l'affiche
• Isoler les secrets par cible plutôt que par convention de nommage
• Repérer la limite de plan qui rend les environnements inopérants sur un dépôt privé gratuit

Pourquoi pas simplement des secrets de dépôt ?

La pratique la plus répandue consiste à ranger tous les secrets au niveau du dépôt et à les distinguer par un préfixe : STAGING_DEPLOY_TOKEN, PROD_DEPLOY_TOKEN. Ça fonctionne, et ça ne protège de rien.

Un secret de dépôt est accessible à tout workflow du dépôt, donc à tout job, donc à toute étape. Un workflow de test qui installe une dépendance compromise peut lire PROD_DEPLOY_TOKEN aussi facilement que le job de déploiement. Le préfixe est une convention humaine ; il n'existe pas pour le moteur d'exécution.

Un secret d'environnement change la nature du contrôle : il n'est délivré qu'aux jobs qui déclarent l'environnement, et seulement après que les règles de protection de cet environnement ont été satisfaites. Le préfixe devient une frontière réelle.

	Secret de dépôt	Secret d'environnement
Qui peut le lire	Tout job du dépôt	Les jobs qui déclarent l'environnement
Quand	Dès le démarrage du job	Après validation des règles de protection
Séparation staging/prod	Par convention de nommage	Par le moteur GitHub
Trace	Aucune	Déploiement enregistré, avec son état

Glissez pour voir

Créer un environnement

L'environnement se crée dans l'interface, pas dans le YAML. C'est volontaire : il porte des règles de gouvernance, qui ne doivent pas être modifiables par quiconque pousse un commit sur une branche.

1. Ouvrir les réglages du dépôt, section Settings > Environments.

2. Créer l'environnement avec New environment, puis lui donner un nom.

   Les noms ne sont pas sensibles à la casse, ne dépassent pas 255 caractères et sont uniques dans le dépôt. Production et production désignent donc le même environnement.

3. Configurer les règles de protection si la cible le mérite (approbations, délai, branches autorisées). Le détail de ces quatre règles fait l'objet de la page suivante.

4. Ajouter les secrets et variables propres à cette cible, dans les sections Environment secrets et Environment variables.

Un environnement non déclaré est créé sans protection

Si un workflow référence un environnement qui n'existe pas, GitHub ne bloque pas le job : il crée l'environnement à la volée, sans aucune règle. Le job s'exécute, le déploiement est enregistré, et l'équipe croit avoir une frontière là où il n'y a qu'un nom. Créez l'environnement et ses règles avant d'écrire le job qui le cite, et méfiez-vous des fautes de frappe : prod n'est pas production.

Rattacher un job à un environnement

Deux formes existent. La forme courte suffit quand le déploiement n'expose pas d'URL :

jobs:
  deploy-staging:
    runs-on: ubuntu-24.04
    environment: staging
    steps:
      - name: Déployer sur staging
        run: ./deploy.sh
        env:
          DEPLOY_TOKEN: ${{ secrets.DEPLOY_TOKEN }}

Le DEPLOY_TOKEN lu ici est celui de l'environnement staging, pas celui du dépôt. Le même workflow, avec environment: production, lira le token de production sous le même nom de variable. C'est ce qui permet d'écrire un job de déploiement unique et de le paramétrer par la cible.

La forme longue ajoute l'URL de déploiement :

jobs:
  deploy-staging:
    runs-on: ubuntu-24.04
    environment:
      name: staging
      url: ${{ steps.deploy.outputs.url }}
    steps:
      - name: Déployer sur staging
        id: deploy
        run: |
          ./deploy.sh
          echo "url=https://staging.mon-app.example.com" >> "$GITHUB_OUTPUT"

Où l'URL apparaît

Renseigner url: n'est pas cosmétique, c'est ce qui relie le déploiement à une adresse consultable. GitHub l'affiche à trois endroits :

• sur la page Deployments du dépôt, en face de l'environnement ;
• dans le graphe de visualisation de l'exécution du workflow ;
• sous forme de bouton View deployment dans la timeline de la pull request, lorsqu'elle s'y applique.

Ce dernier point est le plus utile au quotidien : le relecteur d'une pull request accède à l'environnement de prévisualisation sans quitter la pull request, et sans qu'on lui colle l'URL en commentaire.

Variables d'environnement et secrets : que met-on où ?

Les deux mécanismes portent une valeur propre à la cible, mais ils ne protègent pas la même chose. La règle est binaire : si la fuite de la valeur a un impact, c'est un secret ; sinon, c'est une variable.

	Variable d'environnement	Secret d'environnement
Visible dans les logs	Oui, en clair	Non, masqué par GitHub
Relisible après création	Oui	Non
Exemples	URL d'API, nom de bucket, région, niveau de log	Jeton de déploiement, clé de signature, mot de passe

Glissez pour voir

jobs:
  deploy:
    runs-on: ubuntu-24.04
    environment: production
    steps:
      - name: Déployer
        run: ./deploy.sh --region "$AWS_REGION" --bucket "$BUCKET"
        env:
          AWS_REGION: ${{ vars.AWS_REGION }}      # variable, non sensible
          BUCKET: ${{ vars.BUCKET }}              # variable, non sensible
          DEPLOY_TOKEN: ${{ secrets.DEPLOY_TOKEN }} # secret, masqué

Noter le passage systématique par un bloc env: : un secret interpolé directement dans la ligne de commande apparaît dans les logs de débogage, et le masquage automatique ne rattrape pas une valeur transformée en route.

L'ordre de résolution des secrets

Un même nom peut exister à trois niveaux. GitHub applique une précédence, du plus spécifique au plus général :

Secret d'environnement   (le plus spécifique, gagne)
        |
        v
Secret de dépôt
        |
        v
Secret d'organisation    (le plus général)

Cette précédence est l'outil qui permet de surcharger proprement : une organisation définit un REGISTRY_TOKEN commun, un dépôt le remplace pour son cas particulier, et l'environnement production le remplace encore par un jeton à droits élargis. Le workflow, lui, ne change pas d'une ligne.

Le revers est un piège de diagnostic classique : un secret qui « ne prend pas » est souvent un secret défini au mauvais niveau, masqué par un homonyme plus spécifique. En cas de doute, renommer temporairement l'un des deux lève l'ambiguïté en une exécution.

La limite de plan à vérifier avant de bâtir dessus

Les règles de protection et les secrets d'environnement ne sont pas disponibles sur tous les plans. Sur un plan Free, ils ne fonctionnent que sur les dépôts publics. Un dépôt privé ou interne exige au minimum GitHub Pro pour un compte personnel, ou un plan Team ou Enterprise pour une organisation.

La conséquence est sournoise : sur un dépôt privé gratuit, l'environnement se crée, le job s'exécute, le déploiement apparaît dans l'historique, mais l'approbation ne se déclenche jamais. Vous croyez avoir une porte, vous avez un panneau. Vérifiez le plan avant de fonder une gouvernance de production sur ce mécanisme.

Contrôle de connaissances

Vérifiez que l'essentiel de ce guide est acquis. Les questions portent uniquement sur ce qui vient d'être expliqué ici.

Contrôle de connaissances

Validez vos connaissances avec ce quiz interactif

6 questions

6 min.

70% requis

Informations

• Le chronomètre démarre au clic sur Démarrer
• Questions à choix multiples, vrai/faux et réponses courtes
• Vous pouvez naviguer entre les questions
• Les résultats détaillés sont affichés à la fin

Démarrer le quiz

Lance le quiz et démarre le chronomètre

À retenir

• Un environnement est une cible de déploiement nommée qui porte ses secrets, ses variables et ses règles, et qui transforme un job en déploiement tracé.
• Un secret de dépôt est lisible par tout job du dépôt ; un secret d'environnement n'est délivré qu'aux jobs qui déclarent l'environnement, et après validation de ses règles.
• La clé environment: existe en forme courte (un nom) et en forme longue (name: plus url:).
• L'URL de déploiement s'affiche sur la page Deployments, dans le graphe d'exécution et comme bouton View deployment dans la pull request.
• Un environnement cité mais inexistant est créé automatiquement sans aucune protection : créez-le d'abord dans Settings > Environments.
• Les secrets se résolvent du plus spécifique au plus général : environnement, puis dépôt, puis organisation.
• Sur un plan Free, les protections et secrets d'environnement n'existent que sur les dépôts publics : un dépôt privé exige Pro, Team ou Enterprise.

Pour aller plus loin

• Promouvoir un artefact : Faire traverser staging puis production au même binaire, sans jamais le reconstruire entre les deux.
• Releases et packages : Publier vers GHCR et attacher les artefacts à une release GitHub une fois la cible validée.
• Rollback et concurrence : Ce que l'isolation par environnement permet le jour où il faut revenir en arrière.

×

📖 Voir la documentation →