Updating Environment Variables

All environment variables are managed through dotenv.org and encrypted into .env.vault for deployments. The vault is rebuilt automatically in CI before every deploy -- no manual build or commit needed.

Push Rules

Command	Status	Why
npx dotenv-vault push	Admins only	Full overwrite of the local environment -- replaces everything on dotenv.org with your .env
npx dotenv-vault push <environment>	FORBIDDEN for everyone	Overwrites deployed secrets (API keys, DB URLs, feature flags) with your local .env. This has caused production incidents.

push has no merge, no diff, no conflict detection. It blindly replaces the entire target environment. A stale local value silently overwrote a critical variable and propagated to prod.

Deployed environments (development, test, uat, preprod, production) must only be edited through the dotenv.org web UI, which modifies individual fields instead of doing a full overwrite.

For Developers

You have View + Pull access on dotenv.org. Three commands are all you need:

Getting Started

npx dotenv-vault@latest login
npx dotenv-vault@latest pull

login authenticates you (creates .env.me). pull downloads the local environment to .env.

Staying Up to Date

npx dotenv-vault@latest pull

Run this whenever you're told secrets have changed. Back up your .env first if you have local-only overrides you want to keep.

Requesting Changes

Need a variable added, changed, or removed?

1. Message an admin/lead via Slack or Jira with the variable name, value, and which environments need it
2. Admin makes the change on dotenv.org
3. Run npx dotenv-vault@latest pull to get the update locally

You can always edit your own .env for local-only overrides (different port, debug flags, etc.) without syncing to dotenv.org.

For Admins

All secret changes happen in the dotenv.org web dashboard. Never use the CLI to push to any environment -- the web UI edits individual fields, while push does a full overwrite.

Changing a Secret

1. Log in to dotenv.org and open the goosehead-fastlane project
2. Select the environment and edit the variable
3. Trigger a deploy -- the build-vault CI job auto-rebuilds the vault

For local environment changes, notify the team to pull.

Adding a New Variable

1. Log in to dotenv.org and open the goosehead-fastlane project
2. Use the Compare view to add the variable across all environments that need it (including local for dev machines)
3. Next deploy picks it up automatically
4. Notify the team to npx dotenv-vault@latest pull

Removing a Variable

1. Delete from every environment on dotenv.org (including local)
2. Remove code references
3. Commit and push code changes
4. Notify the team to pull

How the Vault Works

File	Purpose	In Git?
.env	Local dev variables	No
.env.vault	Encrypted secrets for all deployed environments	Yes (fallback)
.env.me	Your dotenv.org credential	No

The build-vault CI job runs npx dotenv-vault build at the start of every deploy pipeline, producing a fresh .env.vault from dotenv.org. Deploy jobs use this artifact to build Docker images with up-to-date secrets.

The .env.vault in Git is a fallback if dotenv.org is unreachable during CI.

Environment Map

dotenv.org	Pipeline	Heroku Prefix
local	N/A (your machine)	N/A
development	Dev	dev-
test	QA	test-
uat	UAT	uat-
preprod	Staging	preprod-
prod	Production	prod-

Access Control

Permission	Developers	Admins
View (see secrets in web UI)	Yes	Yes
Pull (download to local .env)	Yes	Yes
Push (overwrite local env via CLI)	No	Yes
Edit deployed envs (web UI only)	No	Yes

CI Prerequisite

The build-vault job requires a DOTENV_ME variable in GitLab CI/CD Settings (Protected + Masked). See How to Deploy for setup.

Heroku config vars

API Gateway: Do not edit Heroku config vars directly — they are set at runtime via dotenv/config decrypting .env.vault. The only exceptions are Heroku-managed add-on variables: DATABASE_URL, REDIS_URL / REDIS_TLS_URL, and DOTENV_KEY.

Frontend apps (portal, admin): VITE_API_GATEWAY_URL and VITE_DA_BASE_URL are set as Heroku config vars and injected at container startup via config.js. These must be set manually per environment — see Deployment: Heroku Config Vars Reference.

Troubleshooting

"Not authenticated" -- Run npx dotenv-vault@latest login to re-create your .env.me credential.

Local .env is stale -- Run npx dotenv-vault@latest pull.

Deploy didn't pick up secret changes -- Check that (1) the secret is saved on dotenv.org, (2) DOTENV_ME is set in GitLab CI/CD variables, and (3) the build-vault job succeeded in the pipeline.