Nov 18, 20266 min read

Environment Variables vs a Secrets Manager for Backend Secrets

Where plain environment variables are fine, where they leak, what a secrets manager adds, and why most production setups end up injecting secrets from a manager into the environment, with ECS, local development and AI coding agents in mind.

Illustration for Environment Variables vs a Secrets Manager for Backend Secrets

Environment variables are how almost every backend reads its configuration, and the twelve-factor app made them the default place for credentials too. The trouble is rarely the variable itself; it is the copies.

The Stripe key lives in a task definition visible to anyone with ecs:DescribeTaskDefinition, in a CI settings page, in a .env file someone committed in 2023, and in the Slack message where it was shared during onboarding, and when it has to be rotated nobody knows every place it was pasted.

This page compares plain environment variables with a secrets manager on the points that matter in production, and covers the hybrid of the two that production setups usually end up with.

Environment variables vs a secrets manager at a glance

Encore secretsPlain environment variablesSecrets manager (AWS or GCP)
Source of truthEncore's encrypted secrets store, replicated to a secrets manager in your cloud accountWherever the value was pastedOne managed store
Encrypted at restYesDepends on where it was pastedYeswith KMS
Access control and auditPer service on deployWhoever can read the configIAM policies and CloudTrail or Cloud Audit Logs
RotationSet a new value, redeployEdit every copy, redeployVersioned values and rotation functions
In the repositoryNever; code references the nameOften, through .env filesNo
Local developmentSynced values or .secrets.local.cue.env filesUsually a separate local mechanism

Where plain environment variables leak

Environment variables leak through the tooling around them more than through the app. An ECS task definition with plaintext environment entries shows the values to anyone who can describe it and stores them in every revision. CI providers, docker-compose files and Kubernetes manifests become extra copies. Inside the container, child processes inherit the environment, error trackers and debug endpoints sometimes dump it, and on Linux it is readable at /proc/<pid>/environ by the same user. Committed .env files are the most common source of leaked keys, which is why secret scanners exist at all.

What a secrets manager adds

A secrets manager is one encrypted store with access control and an audit trail: an IAM policy says which role may call secretsmanager:GetSecretValue on which secret, and CloudTrail records every read. Values are versioned, so rotation can stage a new version, test it and promote it, and AWS Secrets Manager rotation can run a function to change database passwords on a schedule. The cost is an API call or an injection step, an IAM policy per consumer, and on AWS a per-secret monthly charge.

The hybrid: inject from a manager at start

Most production setups combine the two: ECS can inject a Secrets Manager secret as an environment variable through the task definition's secrets block, so the app still reads process.env.STRIPE_KEY but the value is never written into the task definition:

{ "containerDefinitions": [{ "name": "api", "secrets": [ { "name": "STRIPE_KEY", "valueFrom": "arn:aws:secretsmanager:eu-central-1:123456789012:secret:prod/stripe-AbCdEf" } ] }], "executionRoleArn": "arn:aws:iam::123456789012:role/api-task-execution" }

The ECS documentation spells out the two trade-offs: the value is read when the container starts, so a rotated secret only reaches running tasks after a new deployment, and applications, container logs and debugging tools in the container can still see the environment. The execution role needs secretsmanager:GetSecretValue on each secret, plus kms:Decrypt if it uses a customer-managed key. Apps that must pick up rotations without a restart call the API directly with a short in-process cache. On GCP, Cloud Run offers the same choice between mounting Secret Manager values as environment variables or files.

Local development and AI coding agents

Local development is where secrets managers are least convenient, so teams fall back to .env files, and the file sits in the working tree where every tool can read it. That now includes AI coding agents, which read files in the repository to build context and can echo a key into a diff, a log or a prompt. Keeping production values out of the repository entirely, and giving developers either separate development keys or values synced outside the working tree, removes that path.

Secrets in Encore

Encore

Encore brings infrastructure from code to TypeScript and Go backends, and a secret is declared in code by name, with the value stored outside the repository. You call secret("StripeKey") and read it as a function; the compiler checks that every secret has a value before running or deploying. Values are set per environment type with encore secret set or in the dashboard, stored encrypted, and for your own AWS or GCP account replicated to a secrets manager that Encore provisions in that account (AWS Secrets Manager on AWS), with each service given access only to the secrets it uses. Per the secrets docs, local values are synced to developers' machines by encore run, and a .secrets.local.cue file overrides them for one machine.

Set up the app

Get started
brew install encoredev/tap/encore &&
encore app create
Copy

Run in your terminal to get started locally.

// billing/stripe.ts import { api } from "encore.dev/api"; import { secret } from "encore.dev/config"; import Stripe from "stripe"; const stripeKey = secret("StripeKey"); const stripe = new Stripe(stripeKey()); export const createPortal = api( { expose: true, auth: true, method: "POST", path: "/billing/portal" }, async (p: { customerId: string }): Promise<{ url: string }> => { const session = await stripe.billingPortal.sessions.create({ customer: p.customerId }); return { url: session.url }; }, );
~
$ encore secret set --type prod StripeKeyEnter secret value: ****$ encore secret set --type dev,preview,local StripeKeyEnter secret value: ****

On AWS, the Encore Platform injects the secret into the service's environment at runtime from Secrets Manager, so the trade-offs of injection still apply: the running process can see the value. What changes is that there is one source of truth, no plaintext in task definitions, and no .env file with production values in the repository, so a coding agent working in the codebase cannot read or leak those production values. A local override in .secrets.local.cue is readable if it is present. The agent can add secret("NewVendorKey") in code, and someone with access sets the value.

Best fit: TypeScript or Go backends that want secrets referenced by name in code, values per environment outside the repository, and storage in their own AWS or GCP account.

Which approach to use

Plain environment variables are fine for non-secret configuration and for local development keys that grant nothing in production. For production credentials, keep the source of truth in a secrets manager, inject at start for simplicity or read through the API when rotations must apply immediately, and keep production values out of the repository and out of reach of tools that read it.

Frequently asked questions

Is it safe to store secrets in environment variables?

Yes. Reading a secret from an environment variable at runtime is a common and acceptable pattern. The risk is where the value comes from and who else can see it: plaintext values in task definitions, CI settings, docker-compose files or a committed .env file leak easily, and any process, log or crash dump that captures the environment exposes them. Keep the source of truth in a secrets manager and inject at start.

Does ECS pick up a rotated secret automatically?

No. When ECS injects a Secrets Manager secret as an environment variable, the value is read when the container starts. After a rotation, the running task keeps the old value until you launch new tasks, for example with a forced new deployment of the service. Apps that must see rotations immediately read the secret through the API with a short cache instead.

Deploy to your cloud on AWS and Google Cloud
without managing infrastructure

Encore lets developers and agents define application infrastructure directly in code, then automatically provisions it from local development to production in your AWS or GCP account.

~/orders — claude
Claude Code
Claude Code v2.1.180Opus 5.5~/orders