Environnements et variables

Un projet Bastide sert son application dans un ou plusieurs environnements, et chacun reçoit ses propres variables d'environnement. Cette page explique les genres d'environnement, la différence entre une variable visible et un secret, et la façon de les écrire depuis la console, un agent, la ligne de commande ou l'API.

Les environnements

Un environnement est un lieu de service : il a son adresse, ses déploiements et ses variables. Quatre genres existent dans le modèle.

La grille tarifaire prévoit des environnements personnalisés à partir du palier Standard (2 en Standard, 10 en Pro et en Souverain). Tant que leur création n'est pas servie, un projet travaille avec sa production et ses prévisualisations.

Chaque environnement porte un identifiant env_…. C'est lui qu'exigent la lecture des variables, le déploiement et la restauration. La seule façon de l'apprendre est de lister les environnements du projet.

États d'un environnement

La carte Environnements de la Vue d'ensemble du projet montre, pour chaque environnement, le commit qu'il sert et son état.

• Épinglé : l'environnement sert une version restaurée et ne suit plus les poussées. Voir Restaurer.
• Isolé · bifurcation : une prévisualisation ouverte depuis une bifurcation du dépôt. Elle ne reçoit aucune variable sensible.
• En veille : l'environnement dort faute de trafic et se réveille à la requête suivante.
• supprimé le … : la date à laquelle une prévisualisation sera retirée.

Lever l'épinglage remet en service le dernier déploiement sain et fait de nouveau suivre les poussées. C'est une promotion, réservée au rang Mainteneur : menu « ⋯ » de la ligne, puis Lever l'épinglage, ou l'outil environment_unpin.

Variables et secrets

Une variable a un nom, une valeur et une sensibilité.

• Visible : la valeur se relit, par qui a le rang suffisant (voir le tableau plus bas).
• Secret : la valeur est chiffrée à l'écriture et ne se relit jamais, ni dans la console, ni par l'API, ni par un agent, quel que soit le rang. Un secret se remplace : on écrit une nouvelle valeur sous le même nom.

Par défaut, une variable écrite en production est un secret ; ailleurs, elle est visible. Vous pouvez choisir l'autre réglage à chaque écriture.

L'opération secret.reveal existe au registre pour que la demande soit refusée nommément et journalisée : elle n'est autorisée à aucun rôle. Une lecture qui nomme un secret reçoit le refus secret_never_read.

Quand une variable prend effet

Une modification prend effet au prochain déploiement de l'environnement. La version en ligne garde le jeu de variables avec lequel elle a été construite jusque-là. Après avoir écrit une variable, redéployez : voir Déployer.

Noms autorisés

Un nom commence par une lettre majuscule, puis ne contient que des majuscules, des chiffres et des tirets bas, 64 caractères au plus. Il se lit tel quel dans le code, par exemple process.env.NEXT_PUBLIC_SITE_URL.

Certains noms sont refusés à l'écriture, parce que l'interpréteur ou l'éditeur de liens les lit avant le programme et qu'ils changeraient le comportement de l'image sans laisser de trace dans le plan de construction :

BASH_ENV  DYLD_INSERT_LIBRARIES  DYLD_LIBRARY_PATH  ENV  GIT_EXTERNAL_DIFF
GIT_SSH_COMMAND  IFS  LD_AUDIT  LD_LIBRARY_PATH  LD_PRELOAD  NODE_EXTRA_CA_CERTS
NODE_OPTIONS  PATH  PERL5OPT  PYTHONPATH  PYTHONSTARTUP  RUBYOPT  SHELL  SSL_CERT_FILE

La suppression d'une variable portant l'un de ces noms reste possible.

Héritage

Une prévisualisation hérite des variables de la préproduction du projet, quand elle existe : une variable propre à la prévisualisation masque celle du même nom héritée. La production, la préproduction et un environnement personnalisé n'héritent de rien. L'inventaire dit, pour chaque variable, si elle est propre à l'environnement ou héritée, et de quel environnement.

Variables posées par la plateforme

• PORT : le port sur lequel l'application doit écouter, posé dans le conteneur.
• NODE_ENV : vaut production dans les images Node.js que la plateforme construit.
• DATABASE_URL et DIRECT_URL : quand le projet a sa base PostgreSQL, la plateforme les pose sur l'environnement avant la construction. DATABASE_URL passe par le mutualiseur de connexions en mode transaction ; DIRECT_URL en mode session, avec une seule connexion, pour les outils de migration comme prisma migrate. L'inventaire les marque « Fournie par Bastide ».

Votre propre valeur l'emporte toujours. Si vous écrivez DATABASE_URL, la variable devient la vôtre et la plateforme n'y touche plus. Un dépôt configuré pour SQLite garde sa DATABASE_URL, et une prévisualisation isolée ne reçoit aucune des deux adresses.

Variables requises par le dépôt

Si le dépôt contient un fichier .env.example, chaque variable qu'il déclare doit exister dans l'environnement avant la construction. Sinon, le déploiement est refusé avec variables_requises_manquantes, et le rapport en donne la liste. Une variable que les commentaires du fichier disent facultative (« optional », « facultatif », « laisser vide »…), ou qui y porte une valeur d'exemple sans avoir un nom de secret, produit seulement un avertissement au journal de construction.

Depuis la console

Ouvrez Variables dans le menu du projet. Les onglets du haut choisissent l'environnement ; l'inventaire montre le nom, la sensibilité, l'origine, la révision et la date de chaque variable, jamais sa valeur.

1. Dans le panneau Ajouter une variable, saisissez le nom et la valeur, choisissez Secret ou Visible.
2. Cochez un ou plusieurs environnements : une écriture part vers chacun.
3. Cliquez sur Enregistrer. Un bandeau confirme et propose Défaire pendant 5 minutes.

Modifier relit la valeur d'une variable visible avant de la remplacer. Remplacer sur un secret ouvre un champ vide : l'ancienne valeur ne se montre pas. Remplacer ici sur une variable héritée crée une variable propre qui la masque. La corbeille supprime une variable propre ; la version en ligne la garde jusqu'au prochain déploiement.

Importer un fichier .env

Importer un .env ouvre une fenêtre où coller le contenu, ou choisir un fichier ; vous pouvez aussi glisser le fichier sur la page. Le fichier est lu dans le navigateur, son contenu n'est pas affiché, et chaque variable part ensuite par une écriture séparée.

• Une ligne vide ou commençant par # est ignorée, export en tête est toléré.
• Entre guillemets doubles, \n, \t, \" et \\ sont interprétés, et la valeur peut courir sur plusieurs lignes, ce qui permet de coller une clé PEM. Entre guillemets simples, la valeur est littérale.
• Une clé définie deux fois garde la dernière valeur, avec un avertissement.
• ${AUTRE} n'est pas remplacé : la valeur part telle quelle, avec un avertissement.
• Un fichier de plus de 1 Mo n'est pas lu.

Avant l'envoi, la fenêtre dit ce qui arrivera à chaque variable (ajoutée, remplace la valeur actuelle, masquera celle héritée) et vous laisse cocher Secret ligne par ligne. Une écriture refusée n'arrête pas les autres. Défaire l'import reprend toutes les écritures pendant 5 minutes.

Écrire en production, écrire ailleurs

La production a ses propres opérations, distinctes de celles des autres environnements, avec un rang plus élevé.

Une opération hors production appelée sur la production est refusée (production_environment ou wrong_operation), et le message nomme l'opération à employer. Les opérations de production ne prennent pas d'identifiant d'environnement : il n'y en a qu'une par projet.

Une écriture ou une suppression rend un undoToken : l'outil action_undo la défait pendant cinq minutes, une seule fois, pour le même compte. Un compte de service ne peut ni écrire ni supprimer une variable.

Par un agent

Les outils de variables sont marqués destructifs : votre client MCP vous demande votre accord avant chaque écriture ou suppression. Un agent ne reçoit jamais la valeur d'un secret.

1. environment_list rend les environnements et leurs identifiants.
2. env_list rend l'inventaire d'un environnement, avec les compteurs à confronter aux plafonds.
3. env_write_nonproduction ou env_write_production écrit la variable.

{
  "projectId": "prj_01JQ8ZK4M7NP2RSTVWXYZ34567",
  "environmentId": "env_01JQ8ZK4M7NP2RSTVWXYZ34567",
  "key": "NEXT_PUBLIC_API_URL",
  "value": "https://api.apercu.exemple.fr",
  "sensitive": false,
  "idempotencyKey": "variable-api-apercu-2026-09-14"
}

env_pull_nonproduction et env_pull_production rendent les valeurs visibles. Chaque valeur arrive enveloppée, marquée comme donnée non fiable, et les variables sensibles sont nommées dans clesOmises plutôt que passées sous silence : un appelant sait ainsi qu'elles existent et ne les réécrit pas par erreur.

{
  "variables": {
    "NEXT_PUBLIC_API_URL": {
      "untrusted": true,
      "source": "variable-d-environnement",
      "content": "https://api.apercu.exemple.fr"
    }
  },
  "clesOmises": ["PAIEMENT_CLE_SECRETE"]
}

Par la ligne de commande

bastide environment list --project-id prj_01JQ8ZK4M7NP2RSTVWXYZ34567
bastide env list --project-id prj_01JQ8ZK4M7NP2RSTVWXYZ34567 --environment-id env_01JQ8ZK4M7NP2RSTVWXYZ34567
bastide env write production --project-id prj_01JQ8ZK4M7NP2RSTVWXYZ34567 --key PAIEMENT_CLE_SECRETE --value '<clé>'
bastide env pull nonproduction --project-id prj_01JQ8ZK4M7NP2RSTVWXYZ34567 --environment-id env_01JQ8ZK4M7NP2RSTVWXYZ34567

env pull affiche les valeurs visibles ; il n'écrit pas de fichier. Les écritures et suppressions demandent une confirmation, sauf avec --yes. Dans un répertoire lié par bastide link, --project-id peut être omis.

bastide doctor compare les noms des fichiers .env de votre poste à ceux de l'environnement déployé, sans jamais lire une valeur, et propose la commande qui rapproche les deux côtés.

Conseil. Une valeur passée par --value reste dans l'historique de votre terminal. Pour un secret, préférez la console, ou effacez la ligne de l'historique après coup.

Par l'API

curl -X PUT https://api.bastide.app/v1/projects/prj_01JQ8ZK4M7NP2RSTVWXYZ34567/env/production \
  -H "Authorization: Bearer <votre-jeton>" \
  -H "Content-Type: application/json" \
  -d '{"key": "PAIEMENT_CLE_SECRETE", "value": "<clé>", "idempotencyKey": "secret-paiement-2026-09-14"}'

Les autres routes sont GET /v1/projects/{projectId}/env (inventaire), GET …/env/pull et …/env/pull/production (valeurs visibles), PUT et DELETE …/env (hors production) et …/env/production. Voir la référence de l'API.

Limites

Elles sont les mêmes à tous les paliers.

Erreurs fréquentes

Voir aussi

• Prévisualisations
• Déployer
• Restaurer
• Sécurité des agents
• Comptes de service
• env.write.production, env.pull.nonproduction, secret.reveal

Signaler une erreur sur cette page