Secret Rotation

Rotation as a discipline, not an emergency

A secret that has never been rotated is a secret you cannot rotate. The first time you try, you'll discover three integrations you forgot about, two scheduled jobs that use the old value, and a Vercel environment with the same key set five months ago. Practice rotation when nothing is on fire.

Rotation cadence by type

OIDC tokens — auto, ~1 hour. Don't think about it.
Long-lived API keys (OpenAI, Anthropic, Stripe) — quarterly, or any time a contractor or employee with access leaves.
SSH deploy keys — annually, or on any laptop loss.
Database passwords — on-incident or quarterly.
GitHub PATs — phase out in favor of fine-grained tokens / GitHub Apps; rotate fine-grained ones quarterly.

The rotation procedure

Generate the new value in the provider's UI.
Store as a new secret name (e.g., API_KEY_V2) alongside the existing one.
Update workflows / app config to use V2.
Confirm V2 is in use in production for at least one full traffic cycle.
Revoke the old value in the provider.
Delete the old secret name in GitHub.

This pattern (rotate-with-overlap) avoids the dangerous single-cutover where a new key has a typo and prod goes dark.

Code

Rotation cheat sheet·bash

# 1. Add new secret (overlap)
gh secret set OPENAI_API_KEY_V2 --body "$NEW_KEY"

# 2. Update workflow to use V2 (PR + merge)
#    sed -i 's/OPENAI_API_KEY/OPENAI_API_KEY_V2/g' .github/workflows/*.yml

# 3. Trigger CI to confirm V2 works
gh workflow run ci.yml

# 4. Revoke old key in OpenAI dashboard, then:
gh secret delete OPENAI_API_KEY

# 5. Optional cleanup pass: rename V2 back to canonical name
gh secret set OPENAI_API_KEY --body "$NEW_KEY"
gh secret delete OPENAI_API_KEY_V2

Rotation as a discipline, not an emergency

Rotation cadence by type

The rotation procedure

Code

External links

Exercise

Progress

Comments 0