How to manage environment variables and secrets

Secret management gets treated as a security topic, which is why most teams do it badly. The failures I actually see are operational: the staging Stripe key ends up in production because someone copied the whole env block across, a preview deploy for a fork of your repo gets handed your live database URL, or a secret rotation misses one of four places it was written down and pages someone at midnight.

None of those are cryptography problems. They're problems of where values live and who can see them. This is how to set that up so the wrong value physically can't reach the wrong environment.

Start by separating plain config from secrets

There are two kinds of environment variable and treating them the same is the root of most of the mess. NODE_ENV, LOG_LEVEL, and NEXT_PUBLIC_API_URL are configuration — you'd happily paste them into a ticket. DATABASE_URL, STRIPE_SECRET_KEY, and your JWT signing key are credentials: once revealed, they stay revealed until rotated.

The distinction should be structural, not a naming convention. On PandaStack, a plain var lives in the app record as JSON; a secret lives in a separate encrypted store, and membership in that store is what makes it a secret — there's no is_secret boolean that can drift out of sync with reality. The practical upshot is that a database backup of the app table is provably ciphertext-only for anything sensitive.

# Plain config — readable back in full
curl -X PUT https://api.pandastack.ai/v1/apps/$APP_ID/env/LOG_LEVEL \
  -H "Authorization: Bearer $PANDASTACK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"value":"info","secret":false,"scope":"all"}'

# Secret — encrypted at rest, masked on read, never echoed back
curl -X PUT https://api.pandastack.ai/v1/apps/$APP_ID/env/STRIPE_SECRET_KEY \
  -H "Authorization: Bearer $PANDASTACK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"value":"sk_live_...","secret":true,"scope":"production"}'

Reading them back gives you the shape without the payload, which is what you want a teammate — or a support engineer looking at your app — to be able to see:

{
  "env": [
    { "key": "LOG_LEVEL", "value": "info", "secret": false, "scope": "all" },
    { "key": "STRIPE_SECRET_KEY", "secret": true, "scope": "production",
      "updated_at": "2026-08-19T11:04:00Z", "created_by": "ajay@example.com" }
  ]
}

Scope is the setting that actually prevents incidents

Encryption protects you from a stolen backup. Scoping protects you from yourself, which is the far more likely event. Every variable carries a scope — all, production, or preview — and the deploy only resolves the ones that apply.

• all — the boring default. Same value everywhere: log level, feature flag, region name.
• production — the live keys. A preview deploy never reads these, so a PR from a fork cannot exfiltrate your Stripe key by adding a console.log.
• preview — test-mode keys and throwaway credentials, used only by pull-request environments.

import { Client } from "@pandastack/sdk";
const client = new Client({ apiKey: process.env.PANDASTACK_API_KEY });

// Live key: production only
await client.apps.setEnv(appId, "STRIPE_SECRET_KEY", liveKey,
  { secret: true, scope: "production" });

// Test key: previews only. Same variable name, different value,
// and the two can never be resolved by the same deploy.
await client.apps.setEnv(appId, "STRIPE_SECRET_KEY", testKey,
  { secret: true, scope: "preview" });

Preview environments need their own layer

Per-app preview scope covers an app you already created. It doesn't cover the case that generates the most pull-request environments: a repo where every PR spins up a brand-new throwaway app that didn't exist when you configured anything.

For that, config attaches to the repo rather than the app, and every preview born from that repo inherits it. Set the test-mode keys once and every future PR environment gets them:

curl -X PUT https://api.pandastack.ai/v1/repos/$REPO_ID/preview-env/DATABASE_URL \
  -H "Authorization: Bearer $PANDASTACK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"value":"postgres://...","secret":true}'

This store is preview-only by construction rather than by a filter someone can forget: a production deploy never queries the table at all. A throwaway credential added for one PR is structurally incapable of reaching production, which is a much stronger property than a well-intentioned if statement.

Getting off .env without a copy-paste marathon

Nobody migrates thirty variables through a web form, which is exactly why teams keep the .env file around 'just for now'. Import the file in one call, then delete it:

curl -X POST https://api.pandastack.ai/v1/apps/$APP_ID/env/import \
  -H "Authorization: Bearer $PANDASTACK_API_KEY" \
  -H "Content-Type: application/json" \
  -d "$(jq -n --rawfile dotenv .env.production \
        '{dotenv: $dotenv, secret: true, scope: "production"}')"
# -> {"imported": 31, "total": 31}

import pathlib, pandastack

client = pandastack.Client(api_key="pds_...")
client.apps.import_env(
    app_id,
    dotenv=pathlib.Path(".env.production").read_text(),
    secret=True,
    scope="production",
)

Then make the file impossible to re-add. A gitignore entry is the minimum; a pre-commit hook that greps staged diffs for key-shaped strings is what actually catches it, because the leak is almost never the .env file itself — it's a config sample, a test fixture, or a debug script someone committed at 6pm.

# .git/hooks/pre-commit
if git diff --cached -U0 | grep -nE '(sk_live_|AKIA[0-9A-Z]{16}|-----BEGIN [A-Z ]*PRIVATE KEY)'; then
  echo "refusing: credential-shaped string in staged diff" >&2
  exit 1
fi

The leak nobody plans for: build logs

Env vars are injected at build time as well as at runtime, because half of what you build needs them — a Next.js build inlines NEXT_PUBLIC_ values, a Django collectstatic wants settings, a Vite build reads its own prefix. That means your secrets are present in the build environment, and build tooling is enthusiastic about printing things.

A build script that runs with set -x, an npm postinstall that dumps env for debugging, a stack trace with the connection string in it — all of these end up in a build log that is more widely readable than the secret store. PandaStack redacts known secret values from build logs and from the comment it posts on your pull request, which handles the common case. It cannot redact a value that got base64'd or split across lines first, so the discipline still matters:

1. Never echo env in a build step, even temporarily. 'Temporarily' means it's in the log forever.
2. Keep secrets out of NEXT_PUBLIC_, VITE_, or any client-visible prefix — those are compiled into the JavaScript bundle you ship to browsers, which no server-side redaction can help with.
3. If a build genuinely needs a credential, prefer a short-lived token over a long-lived one, so the blast radius of a log leak has an expiry.

Rotating without a maintenance window

The reason rotation gets deferred is that people picture it as: update the value, redeploy, hope. The safe version is boring and takes ten minutes, and it works because most providers let two credentials be valid at once.

1. Issue a new credential at the provider. Both old and new are now valid.
2. Update the variable on the app. Changing env invalidates the baked deploy artifact, so the next deploy or the next wake picks it up — there is no stale-cache window to reason about.
3. Deploy, and confirm the app is healthy on the new value.
4. Revoke the old credential at the provider.
5. Grep your other systems for it — CI secrets, a teammate's laptop, the cron job nobody owns. Step 5 is the one that gets skipped and the one that causes the 3am page.

If a credential has actually leaked, invert the order: revoke first and accept the downtime. A leaked key with a five-minute overlap window is a leaked key.

What 'encrypted at rest' should mean

Every platform claims it, and the phrase covers a wide range of actual guarantees. Three questions separate the meaningful implementations from the marketing:

• Is the value encrypted, or is the disk encrypted? Full-disk encryption protects against someone stealing the drive. It does nothing about a leaked database dump, which is the realistic threat.
• Is the ciphertext bound to its owner? PandaStack seals each value with AES-256-GCM using the app or repo identity as additional authenticated data, so a ciphertext row copied from one app to another fails to decrypt rather than silently working. Without that binding, a database-level write is a privilege escalation.
• Can the value be read back through the API? If yes, the encryption is protecting the storage layer and nothing else. Read paths should return masked values, and the only component that decrypts should be the deploy itself.

The setup, condensed

1. Mark credentials as secrets; leave plain config plain. Don't encrypt LOG_LEVEL and feel safe.
2. Scope production keys to production and test keys to preview. Same variable name, different values, no branching in your code.
3. Put repo-level preview config on the repo, so PR environments inherit it without anyone configuring anything.
4. Import .env once, then delete it and add a pre-commit guard.
5. Never echo env in a build step; never put a secret behind a client-visible prefix.
6. Rotate by adding-then-revoking, and finish by grepping every other system for the old value.

None of this is exotic. It's mostly about making the unsafe thing structurally impossible rather than merely discouraged — which is why scoping earns its keep long before encryption does.