Secrets & Environment Variables

Scenario

Your application integrates with external services and requires configuration such as:

• database URLs;
• API keys;
• OAuth credentials;
• signing secrets.

The repository uses environment variables and keeps an example environment file containing safe placeholder values.

You want coding agents to avoid accidentally committing secrets or exposing server-only configuration to browser code.

Repository Structure

application/
├── src/
│   ├── config/
│   │   └── env.ts
│   ├── server/
│   └── client/
├── .env.example
├── .gitignore
└── AGENTS.md

AGENTS.md

# Project Instructions

## Secrets

- Never commit real API keys, passwords, tokens, private keys, or production credentials.
- Never place secrets in source code, tests, documentation examples, or committed configuration.
- Use placeholder values in `.env.example`.

## Environment Variables

- Access environment variables through the existing configuration module when one exists.
- Document newly required variables in `.env.example`.
- Preserve the project's existing validation for required environment variables.

## Client and Server Boundaries

- Treat credentials as server-only unless they are explicitly designed to be public.
- Do not expose server secrets through browser bundles, client-visible configuration, API responses, or logs.
- Follow framework-specific public environment-variable conventions carefully.

## Logging

- Do not log secrets or complete authorization credentials.
- Redact sensitive configuration from diagnostic output.

## Testing

- Use test credentials or safe placeholder values in tests.
- Do not make tests depend on production secrets.

What This Does

This establishes a safe configuration workflow.

For example:

.env

may contain local secret values.

But:

.env.example

should contain only placeholders such as:

DATABASE_URL=postgresql://user:password@localhost:5432/app
PAYMENT_API_KEY=replace-with-local-test-key

The example file documents configuration requirements without distributing real credentials.

What This Does NOT Do

The instructions do not imply that every environment variable is secret.

For example:

APP_ENV
PUBLIC_SITE_URL
FEATURE_FLAG

may be non-sensitive.

The important distinction is whether exposure creates security risk.

The file also does not suggest inventing custom secret encryption inside the application.

Production secret storage may be handled by:

deployment platform
cloud secret manager
CI/CD secret store
container environment

depending on the infrastructure.

Why These Instructions Matter

Coding agents often need realistic values while implementing integrations.

A dangerous shortcut is:

const apiKey = "sk-live-real-secret-value";

Even if the value is later removed, it may remain in:

Git history
logs
code review systems
build artifacts

Another common problem is accidentally exposing server configuration to frontend code.

For example, frameworks may intentionally expose environment variables with specific prefixes to browser bundles.

A server credential placed in that namespace can become visible to users.

Key Decisions

Keep secrets out of source control

Repositories should describe required configuration, not contain production credentials.

Document variables safely

When adding:

PAYMENT_WEBHOOK_SECRET

also update the project's safe configuration documentation or .env.example.

Respect client/server boundaries

A value available during a frontend build may become public.

Agents should understand the framework's environment-variable exposure model before moving configuration into client code.

Redact logs

Diagnostic logging should not turn authentication headers or configuration objects into credential leaks.

Rotate exposed secrets

If a real secret is discovered in repository history or another exposed location, removing the text from the latest file is not sufficient.

The credential should be treated according to the organization's secret-rotation and incident process.

When to Use This Pattern

Use this pattern when:

• the application uses external APIs;
• database credentials exist;
• OAuth or signing secrets exist;
• frontend and backend configuration share a repository;
• developers use environment variables locally.

Almost every production application benefits from a small, explicit secret-handling section.