managing-service-env

Managing service env

Use this skill whenever a company service gets a new environment variable or a production value changes.

The goal is simple:

• local files document the keys
• app code validates the keys
• Railway stores production values
• only real secrets are sealed

Use Seal only for high-sensitivity values.

Local files

Use these files:

File	Purpose
.env.example	Committed reference for every required key
.env.local	Local developer values, never committed
src/lib/env.ts	Runtime validation with zod

Make sure .gitignore contains:

.env*.local

Rules:

• Add every required key to .env.example.
• Keep .env.example safe: empty placeholders, public values, or safe local-only defaults.
• Never commit real production secrets.
• Validate server runtime variables in src/lib/env.ts when it is safe for the framework path.
• Do not expose secrets through NEXT_PUBLIC_* or any client-side env prefix.
• Follow the owning skill if it has a framework-specific exception.

Railway variables

Railway Variables are the source of truth for production values.

Use the linked project and service. Before setting variables, confirm:

railway status --json

Set non-secret values directly:

railway variable set AUTH_URL=https://web-production-abc123.up.railway.app --service web --environment production
railway variable set AUTH_TRUST_HOST=true --service web --environment production

Set reference variables with quotes so the shell does not expand them:

railway variable set 'DATABASE_URL=${{Postgres.DATABASE_URL}}' --service web --environment production

Set secret values through stdin when possible. This avoids shell history leaks:

openssl rand -base64 32 | railway variable set AUTH_SECRET --stdin --service web --environment production

You can list variables for a service:

railway variable list --service web --environment production

After adding, changing, or deleting variables, review Railway staged changes and deploy or redeploy when needed.

Seal policy

Railway sealed variables are available to builds and deployments, but their values cannot be read back from the UI, API, or CLI.

Seal only high-sensitivity values.

Seal these

Variable type	Examples
Passwords and connection strings with credentials	DATABASE_URL, REDIS_URL
Signing or encryption secrets	AUTH_SECRET, ENCRYPTION_KEY, JWT_SECRET
OAuth client secrets	OKTA_CLIENT_SECRET
API tokens and provider keys	LITELLM_API_KEY, OPENAI_API_KEY, ANTHROPIC_API_KEY, GEMINI_API_KEY, OKTA_API_TOKEN
Webhook signing secrets	STRIPE_WEBHOOK_SECRET, SLACK_SIGNING_SECRET
Private package or registry tokens	NPM_TOKEN, GITHUB_TOKEN

Do not seal these

Variable type	Examples
Public URLs	AUTH_URL, LITELLM_BASE_URL, public callback URLs
Public issuer URLs	OKTA_ISSUER
Client IDs and app IDs	OKTA_CLIENT_ID, OAuth client IDs
Boolean flags	AUTH_TRUST_HOST, feature flags
Environment names	NODE_ENV, RAILWAY_ENVIRONMENT_NAME
Service names and domains	custom domain names, service labels

Why keep public config readable:

• Sealed values cannot be unsealed.
• Sealed values cannot be read back for debugging.
• Sealed values are not provided by railway variable list, railway run, or railway shell.
• Sealed values are not copied to PR environments, duplicated environments, or duplicated services.

How to seal

Railway CLI can set variables, but sealing is a dashboard action.

After every Railway env setup or audit, print a seal action list for the user. Do not only say "seal the secrets". Name each variable and explain why.

Use this format:

Required Railway Seal actions:
1. Open Railway -> project -> service -> Variables.
2. For each variable below, open the three-dot menu and choose Seal.
3. Confirm only after the value is correct. Sealed values cannot be read back.

Must seal:
- AUTH_SECRET - signing secret
- DATABASE_URL - contains database credentials
- OKTA_CLIENT_SECRET - OAuth client secret

Keep readable:
- AUTH_URL - public app URL
- AUTH_TRUST_HOST - boolean flag
- OKTA_CLIENT_ID - public app ID
- OKTA_ISSUER - public issuer URL

The list must match the actual service. Add provider keys, webhook secrets, registry tokens, and private API tokens to Must seal. Add public IDs, URLs, domains, service names, and flags to Keep readable.

Do not claim the Railway env work is fully complete until one of these is true:

• the user confirmed the required variables were sealed in Railway
• the remaining manual seal actions are listed clearly as pending

In Railway:

1. Open the project.
2. Open the service.
3. Go to Variables.
4. Use the variable three-dot menu.
5. Choose Seal.

Seal only after the value is correct. If a sealed value is wrong, update it with the correct value. You cannot read the old value back.

Per-service checklist

• .env.example contains every required key.
• .env.local is ignored by git.
• src/lib/env.ts validates runtime keys where appropriate.
• Production values are set in Railway Variables.
• Secret values were set through stdin or the dashboard, not pasted into shell history.
• Only high-sensitivity variables are sealed.
• IDs, URLs, domains, and flags are readable.
• Railway staged changes were reviewed and deployed when needed.
• No secret is prefixed with NEXT_PUBLIC_ or exposed to client code.

Common mistakes

• Using Seal for public config. This makes debugging harder and does not add useful security.
• Leaving API keys readable. API keys, tokens, passwords, and signing secrets must be sealed.
• Pasting secrets into commands. Prefer railway variable set KEY --stdin for secrets.
• Forgetting reference variable quotes. Use quotes around ${{Service.KEY}}.
• Putting production secrets in .env.example. Use empty placeholders or safe local values only.