Principles
- Never commit secrets to version control
- Centralize secrets in one secure location
- Use environment variables for runtime access
- Rotate regularly and audit access
Environment Variables
Structure
project/
├── .env # Local secrets (git-ignored)
├── .env.example # Template (committed)
└── .gitignore # Must include .env
.env.example Template
# API Keys
ANTHROPIC_API_KEY=your-key-here
OPENAI_API_KEY=your-key-here
# Service Credentials
DATABASE_URL=postgres://user:pass@host:5432/db
REDIS_URL=redis://localhost:6379
# Feature Flags
DEBUG=false
LOG_LEVEL=info
Loading Environment Variables
# In shell
source .env
# Or use dotenv in code
npm install dotenv
// index.js
require('dotenv').config();
const apiKey = process.env.ANTHROPIC_API_KEY;
Git Safety
Essential .gitignore
# Secrets
.env
.env.local
.env.*.local
*.pem
*.key
credentials.json
secrets/
# IDE
.idea/
.vscode/settings.json
# OS
.DS_Store
Thumbs.db
Pre-commit Hook
Prevent accidental commits of secrets:
#!/bin/sh
# .git/hooks/pre-commit
# Check for potential secrets
if git diff --cached --name-only | xargs grep -l -E "(API_KEY|SECRET|PASSWORD|TOKEN)=.+" 2>/dev/null; then
echo "ERROR: Potential secrets detected in staged files"
exit 1
fi
Cloud Secrets Management
Google Cloud Secret Manager
# Create secret
gcloud secrets create my-api-key --data-file=./secret.txt
# Access in code
gcloud secrets versions access latest --secret=my-api-key
# Use in Cloud Run
gcloud run services update my-service \
--set-secrets=API_KEY=my-api-key:latest
Environment-Specific Secrets
production/
├── secrets/ # Stored in cloud secret manager
└── .env.production # Non-sensitive config
development/
├── .env.local # Local development secrets
└── .env.development # Non-sensitive config
Agent-Specific Patterns
Centralized .env in HQ
agents-squads/
├── hq/
│ └── .env # All secrets here
├── engineering/
│ └── (references hq/.env)
└── website/
└── (references hq/.env)
Accessing Secrets in Agents
# Agent: Deploy Service
## Prerequisites
- GOOGLE_CLOUD_PROJECT set in environment
- ANTHROPIC_API_KEY available
## Instructions
1. Load environment: `source ../hq/.env`
2. Run deployment: `gcloud run deploy ...`
MCP Server Credentials
{
"mcpServers": {
"supabase": {
"command": "npx",
"args": ["-y", "@supabase/mcp-server"],
"env": {
"SUPABASE_ACCESS_TOKEN": "${SUPABASE_ACCESS_TOKEN}"
}
}
}
}
Audit & Rotation
Regular Rotation Schedule
| Secret Type | Rotation Frequency |
|---|
| API Keys | 90 days |
| Database passwords | 30 days |
| Service accounts | 180 days |
| Access tokens | 24 hours (auto) |
Audit Checklist
Emergency Response
If Secrets Are Leaked
- Immediately rotate the compromised credentials
- Revoke any active sessions
- Audit access logs for unauthorized use
- Clean git history if committed:
# Remove from history (requires force push)
git filter-branch --force --index-filter \
"git rm --cached --ignore-unmatch .env" \
--prune-empty --tag-name-filter cat -- --all
- Update all systems using the credential
- Document the incident
Force pushing rewrites history - coordinate with your team before running git filter-branch or git push --force.
Best Practices
- Use
.env.example for documentation
- Never log or print secrets
- Use secret managers in production
- Implement least-privilege access
- Automate rotation where possible
- Encrypt secrets at rest
