Définir les variables d'environnement par environnement

Orbit lets you decide exactly which builds see which environment variables, so production credentials never end up in a publicly reachable branch preview. This guide covers how scope and precedence…

Orbit vous permet de décider exactement quelles versions voient quelles variables d'environnement, donc les identifiants de production ne se retrouvent jamais dans une prévisualisation de branche accessible au public. Ce guide couvre le fonctionnement de la portée et de la priorité, comment ajouter une variable réservée à la production, le comportement de l'héritage de staging, et comment vérifier ce qu'une version a réellement reçu.

Pourquoi c'est important

Une prévisualisation de branche obtient une URL publique. N'importe qui ayant le lien peut la charger. Si une variable est limitée à chaque environnement, elle est injectée dans la version de cette prévisualisation, et quoi que la prévisualisation en fasse, elle le fait avec vos identifiants de production.

C'est la raison entière de l'existence de cette page. Tout ce qui suit est au service d'une règle : les secrets de production appartiennent à la portée de production, et nulle part ailleurs.

Fonctionnement de la portée

Chaque variable a une portée qui décide si elle est injectée au moment de la version.

Portée	Injectée dans
Tous les environnements (à l'échelle du projet)	Chaque version de ce projet, sauf si vous la limitez
Un remplacement d'environnement spécifique	Versions de cet un seul environnement

Quand la même clé existe aux deux niveaux, la plus spécifique l'emporte. Un remplacement au niveau de l'environnement bat une variable à l'échelle du projet avec la même clé. La page Env vars l'indique dans le sous-titre de la section Tous les environnements : les variables à l'échelle du projet sont disponibles dans chaque version, et les remplacements au niveau de l'environnement ont priorité.

Les variables à l'échelle du projet peuvent aussi être limitées sans devenir un remplacement. Le contrôle Disponible dans offre trois types d'environnement (production, staging, preview) et vous pouvez désélectionner n'importe lequel d'entre eux.

Ajouter une variable avec une portée

Ouvrez votre projet dans Orbit et cliquez sur l'onglet Env vars.
Faites défiler jusqu'au formulaire Add variable en bas.
Remplissez la KEY et la value.
Utilisez le menu déroulant Scope :
- All environments (project-wide) l'injecte dans chaque version.
- [Environment name] only ([type] override) le limite à cet un seul environnement.
Si vous avez choisi l'échelle du projet, utilisez les boutons Available in pour désélectionner les types d'environnement vers lesquels cette variable ne doit pas arriver.
Cochez Mark as secret pour tout ce qui est sensible.
Cliquez sur Add.

Avant de valider, le formulaire vous dit ce qu'il est sur le point de faire. Un remplacement affiche un avis disant qu'il s'appliquera uniquement aux versions de cet environnement et que les variables à l'échelle du projet s'appliquent toujours ailleurs. Une variable à l'échelle du projet limitée affiche exactement quels types d'environnement la recevront.

Ajouter une variable réservée à la production

Deux routes équivalentes :

Dans le menu déroulant Scope, choisissez votre environnement de production (il porte un badge production vert), ou
Gardez la portée comme All environments et désélectionnez staging et preview sous Available in.

De chaque façon, la variable est absente quand une prévisualisation ou une version de staging s'exécute.

"Absent" signifie absent, pas vide. Le code qui lit process.env.STRIPE_SECRET_KEY dans une version de prévisualisation obtient undefined, et selon la façon dont il est écrit cela peut lever une exception au moment de la version ou, pire, prendre silencieusement une mauvaise branche. Donnez aux prévisualisations une valeur de mode test plutôt que pas de valeur du tout.

Le motif sûr

Le motif qui résout cela proprement pour la plupart des projets :

Ajoutez l'identifiant production limité à l'environnement de production uniquement.
Ajoutez une variable avec la même clé, contenant une valeur de test ou sandbox, à portée à l'échelle du projet.

Les versions de production obtiennent la valeur limitée à la production parce que la portée plus spécifique l'emporte. Les prévisualisations et staging obtiennent la valeur de test. Rien n'est indéfini nulle part, et aucun identifiant de production n'atteint jamais une prévisualisation.

Appliquez-le à :

Les URLs de base de données de production
Les clés secrètes du fournisseur de paiement, en utilisant les clés de test du fournisseur pour les prévisualisations
Les clés d'envoi d'e-mail, pour que une prévisualisation ne puisse pas envoyer un mail aux vrais clients
Les jetons admin et les secrets de signature
Tout ce qui a un coût par appel

Hériter des variables de production dans staging

Si votre environnement de staging est proche de la production et vous voulez seulement remplacer quelques valeurs, vous n'avez pas à tout dupliquer.

Dans Settings, trouvez Staging: environment variables et activez Inherit production env vars. Les variables de production sont alors fusionnées dans les versions de staging à priorité inférieure aux remplacements spécifiques à staging, donc tout ce que vous avez défini explicitement sur staging gagne toujours.

L'héritage copie les valeurs de production dans les versions de staging, y compris les identifiants de production. Activez-le uniquement si votre environnement de staging est protégé. Staging supporte à la fois un mot de passe et une liste blanche IP, dans les sections Staging: access protection et Staging: IP allowlist de Settings. Activer l'héritage pour un environnement de staging non protégé récréé exactement l'exposition dont parle cette page.

Afficher et éditer les variables existantes

L'onglet Env vars groupe les variables dans :

All environments en haut, contenant des variables à l'échelle du projet
Une section réductible par environnement, contenant les remplacements de cet environnement, avec un compte de combien il y en a

Au-dessus se trouve une boîte de recherche et un filtre Secrets only.

Les badges à côté de chaque nom de variable montrent quels types d'environnement elle atteint. Une variable affichant production et preview mais pas staging sera manquante des versions de staging, et cette rangée de badge est le moyen le plus rapide d'auditer une longue liste.

Cliquez sur l'icône d'édition pour modifier une valeur. La valeur actuelle d'une variable secrète ne peut pas être révélée, seulement remplacée.

Copier et comparer entre les environnements

Copy variables between environments copie un ensemble entier d'une portée à une autre. Choisissez un From et un To, cochez optionnellement Overwrite variables that already exist in the target, et cliquez sur Preview pour voir combien seront ajoutés, mis à jour et ignorés avant de valider.

La page Env sync check compare la production et staging clé par clé et rapporte ce qui existe dans un seul, ce qui a des valeurs différentes, et ce qui correspond. C'est le bon premier arrêt pour "staging fonctionne et production non", ou l'inverse.

Des valeurs différentes entre production et staging est normal et attendu pour la plupart des secrets. La page de synchronisation le dit. Ce que vous cherchez est une clé présente dans un environnement et manquante de l'autre.

Partager des variables entre les projets

Si plusieurs projets ont besoin du même identifiant, utilisez un groupe env plutôt que de le coller dans chaque projet. Allez à Orbit, puis Env groups, créez un groupe, ajoutez les variables, et liez les projets qui en ont besoin.

Les variables de groupe sont injectées au moment de la version et se situent au bas de l'ordre de priorité : les variables au niveau du projet et au niveau de l'environnement ont priorité sur les variables de groupe. Vous pouvez avoir jusqu'à 20 groupes sur un compte.

Supprimer un groupe supprime ces variables des futures versions de chaque projet lié. Les versions déjà terminées ne sont pas affectées.

Importer en masse

Le bouton Import .env ouvre une boîte de collage. Collez un fichier .env, choisissez une portée, et Orbit rapporte combien de variables il a trouvé et combien il marquera comme secret. Les clés contenant SECRET, TOKEN, KEY, PASSWORD et des termes similaires sont signalées automatiquement. Il y a une option Overwrite existing variables with the same key, désactivée par défaut.

Download .env produit un modèle de noms uniquement, sans valeurs, pour partager avec un coéquipier qui fournira les leurs.

Choisissez la portée dans la dialogue d'importation avant de cliquer sur Import, pas après. Importer un .env de production entier à portée à l'échelle du projet pousse chaque identifiant de production dans vos versions de prévisualisation en une action, et la correction est de les supprimer et les réajouter, pas de changer un paramètre.

Vérifier ce qu'une version a réellement reçu

La page de détail de chaque déploiement énumère les clés de variable d'environnement injectées au moment de la version et les compare à votre configuration actuelle : ajoutées, modifiées, supprimées, inchangées. Les clés teinte cyan proviennent d'un remplacement spécifique à l'environnement, les grises du niveau du projet.

Les valeurs ne sont jamais stockées ou affichées. Survoler une clé donne une empreinte SHA-256, ce qui est suffisant pour confirmer que deux environnements contiennent la même valeur sans la révéler.

Si la configuration a changé après que ce déploiement ait été construit, la page le dit avec un avis Environment variables updated since this deployment et vous rappelle que le changement ne prendra effet que lorsque vous redéploierez.

Les changements de variables ne s'appliquent jamais au déploiement qui est déjà en direct. Ils sont injectés quand une version s'exécute. Après avoir changé quelque chose sur lequel votre app dépend, redéployez.

Lectures connexes

Environment Variables pour les bases, les secrets et les règles de préfixe de framework
Branch Preview Deployments in Orbit pour le fonctionnement des prévisualisations publiques
Viewing Build Logs pour le diff de variable au moment de la version