Adding & Rotating

This page is the how-to: add a new config secret, push it live, rotate one safely, and the rules and gotchas that keep real values out of git. Never reproduce a real secret value here or anywhere — placeholders like <your-secret> only.

Step 1: Add a new secret

Say a new integration needs an ACME_API_KEY. There are three coordinated edits, in this order.

First, declare it in the Zod schema so the app knows it exists and validates it. Make it required (z.string()) unless there's a real fallback.

const envSchema = z.object({
  // ...existing keys
  ACME_API_KEY: z.string(),
});

Then expose it through the shaped config so services read it via ConfigService instead of process.env directly — group it with related keys.

return {
  // ...
  acme: { apiKey: process.env.ACME_API_KEY },
};

Then add it to every environment's secrets file — infra/staging/secrets.staging.yaml and infra/prod/secrets.prod.yaml — and to your own .env.local. Miss one environment and that environment won't boot, because the schema is required.

# Acme
ACME_API_KEY: '<your-acme-key>'

Step 2: Sync it to Railway

With the YAML updated, push it to the deployed environment. Export a Railway project token and run the sync script against the env folder.

export RAILWAY_TOKEN='<your-railway-project-token>'
scripts/sync-railway-env.sh infra/staging
# verify staging boots, then:
scripts/sync-railway-env.sh infra/prod

The script batches all variables into one railway variable set per service and triggers exactly one deploy each, so the new key goes live applied — not staged. The mechanics of that script live in Where They Live.

Step 3: Rotate a secret

Rotation is the same machinery with old and new overlapping briefly. To rotate, say, RESEND_API_KEY:

1. Generate a new value in the provider's dashboard (Resend, Cloudflare, Microsoft, etc.). Keep the old one valid for now.
2. Replace the value in the relevant secrets.*.yaml (and .env.local for local).
3. Run scripts/sync-railway-env.sh infra/<env> — this redeploys the service with the new value.
4. Confirm the feature works against the new credential, then revoke the old value at the provider.

For product secrets, rotation is different and simpler: an API key has a revokedAt column, so ApiKeyService.revoke(id) stamps it and verify immediately stops matching it — mint a fresh key, hand it over, revoke the old. No redeploy needed, because product secrets live in the database, not the environment. See Secrets at Rest for how those are stored.

Never-commit rules

Two mechanisms keep config secrets out of git.

.gitignore blocks every .env variant. Local secret files can't be committed even by accident, because every dotenv filename is ignored.

# dotenv environment variable files
.env
.env.local
.env.development
.env.production
.env.staging
.env.prod

The secrets.*.yaml files carry a loud warning and a private-repo assumption. Each file's header says DO NOT commit to a public repo — this file contains real secrets. They exist in the repo precisely so the deploy mechanism (the sync script reading from disk) can find them — which only works because this repository is private. The header is a standing reminder of that assumption.

And there is no .env.example — the absence is the policy: nothing in the tree advertises the key names with fillable slots next to real-looking values.

Gotchas

A few traps that bite people working with secrets here.

Where to go next