Import a .env file
Bring a .env or .env.op file into an app's environment, with secrets created and 1Password references synced, and export the environment back as a file.
An import is planned first and applied in one transaction: secrets created, rotated and granted, and the environment replaced. Either all of it lands, or none of it does. No value is ever sent back. Replace app-id with the app's id.
Prerequisites
- Permission for
deploy:ManageEnvon the app. A file withop://references also needssecrets:UseSecretSourceon the source, already for the preview. Applying needs, as the plan requires,secrets:CreateSecret(new secrets),secrets:RotateSecret(a new value for a key that is already a secret) andsecrets:GetSecretValue(anews-secret://binding). To redeploy in the same step,deploy:DeployApp. - In the console, also
deploy:DescribeAppto open the app's page (without it the page is not found).
Import the file
- Open the app's Environment tab, then choose Import .env.
- Paste the file into the text box, or choose Upload file and pick it.
- For Mode, choose Merge (keep variables the file omits) or Replace (remove variables the file omits).
- (Optional) When the file holds
op://references and several secret sources are connected, for Source for new references, choose one. Automatic (the one that reaches the vault) is the default. - Choose Preview. Each key is listed with its Change (Add, Update, Unchanged, Remove or Error), what it is Stored as and What happens.
- (Optional) For a key detected as Plain or Secret, change Stored as. The preview runs again.
- Choose Apply, or Apply & redeploy (shown only with
deploy:DeployApp). Both stay unavailable until a preview without errors. The dialog reports how many variables were added, updated and removed, and whether a redeploy was queued.
dcloud deploy env import app-id --content "$(cat .env.op)" --preview
dcloud deploy env import app-id --content "$(cat .env.op)" --redeploy--mode replace removes variables the file does not mention. --classify overrides how a key is
stored, once per key: --classify API_URL=plain --classify STRIPE_KEY=secret.
POST /deploy/api/apps/3f1c2b4a-5d6e-4f70-8a91-b2c3d4e5f601/env/import
{ "content": "LOG_LEVEL=info\nAPI_TOKEN=op://Production/api/token\n", "mode": "merge", "preview": true }Send the same body without preview to apply it; classify switches a key between plain and
secret.
How each line is stored
| Value | Stored as |
|---|---|
op://vault/item/field |
a synced secret, through the source that synced it or reaches the vault |
ews-secret://NAME |
a binding to the existing secret NAME |
| looks sensitive | a new secret, encrypted under your CMK, granted to deploy and bound |
anything else, and NEXT_PUBLIC_*, VITE_* |
a plain variable |
A value looks sensitive if any of these hold:
- its name says so (
SECRET,PASSWORD,TOKEN,API_KEY,…_KEY,DSN, …); - it is a URL with a password;
- it starts with a known credential prefix (
sk-,ghp_,AKIA,-----BEGIN, …); - it is long and random.
Numbers and flags stay plain. A key that already exists keeps the kind it has. The preview is the plan: every key is marked add, update, unchanged, remove or error with what will happen, and references are checked against 1Password. Nothing is applied while any key has an error.
merge(default) keeps variables the file does not mention;replaceremoves them.- A pasted value for a key that is already a secret rotates that secret, writing a new version so the old one can be rolled back.
- A reference already synced elsewhere reuses that synced secret. When several secret sources reach a vault, choose the source for new references.
- A multi-line value is an error on its key: "Multi-line values are not supported (each variable is written as one line). Store it base64-encoded, or as a file in the image."
- A key that the app's database binding generates is an error too: "
KEYis generated by this app's database binding".
An apply that would create a secret needs an enabled encryption key in KMS; without one the import
is refused with 409 "No enabled encryption key in this organization — create one under KMS
first". Applying a plan that still has errors answers 422 "The import has N error(s); nothing was
changed". The file can be at most 512 KiB.
Export the environment
On the Environment tab, choose Export, or:
dcloud deploy env export app-idThe file holds plain values in full; synced secrets as their op:// reference, so the export of a
.env.op import is a .env.op; other secrets as ews-secret://NAME; database-binding variables as
comments. No secret value is ever exported. The file imports back unchanged.
Result
The app's environment holds the file's variables. Without a redeploy, the panel shows Saved, not running. until someone redeploys; see Set environment variables.