A Secrets Rotation Runbook Prompt for Zero-Downtime Rotations

The secret rotation looks done. The new key is generated, the vault is updated, the deploy went green. Then a batch job that runs every six hours wakes up, tries the old cached key, and fails, because nobody mapped that job as a consumer. A secrets rotation runbook prompt exists to prevent exactly that: it forces you to find every consumer before you revoke anything.

Secret rotation is replacing a credential, an API key, a database password, a token, with a new one while every service that uses it keeps working. The hard part isn't generating the new secret. It's the dependency graph around the old one.

This is the rotation-and-audit companion job inside the Polyglot Secrets Management Playbook. The single prompt below runs one rotation.

Why the checklists stop short

Moments Log publishes a secrets rotation checklist with 12 items and the right opening move: start with a rotation inventory, not the new secret. Groundcover covers how secret rotation works. Doppler writes about rotating without downtime.

They agree on the principle: the dependency graph is the real work. What they don't do is build the runbook for your specific secret. A 12-item checklist is a reminder; it doesn't know your batch job exists. The prompt takes your credential and its consumers and writes the sequenced, this-secret runbook, which is the artifact you actually follow during the rotation.

What you can do with this prompt

• Map every consumer of a credential before touching the secret itself
• Sequence a dual-secret overlap so old and new work simultaneously
• Get the verification signals that prove rotation worked, beyond a green deploy
• Time the old-secret revocation so nothing fails on a stale cache
• Set a rollback window that's honest about when you can still revert
• Produce a runbook tied to this secret, not a generic 12-step list

Anatomy of the prompt

Variables
  {{secret_description}} – what the credential is and what it protects
  {{consumers}}          – services, jobs, vendors that read it
  {{storage_method}}     – vault, env var, secrets manager
  {{caching_notes}}      – where the secret gets cached (pools, jobs)
  {{risk_tier}}          – how sensitive, drives cadence

Prompt
  Role: platform engineer writing a zero-downtime rotation runbook.
  Map consumers, sequence a dual-secret overlap, define verification
  signals, time revocation, and set a rollback window.

Output contract (locked)
  ## Consumer map (each: name, how it reads the secret, caching)
  ## Rotation steps (numbered, dual-secret overlap)
  ## Verification (auth-success signals, not just deploy status)
  ## Revocation timing + rollback window

The {{caching_notes}} variable is the one that catches the 3am failure. A connection pool or a cron that cached the old secret won't notice the new one until it reconnects, so the runbook has to account for the lag.

How to run it

1. Inventory the consumers first

{{consumers}} is the whole game. List every service, job, and vendor that reads the secret. Miss one and the runbook is confidently incomplete. This is the step worth over-investing in.

2. Flag where it's cached

{{caching_notes}} tells the prompt where the old secret lingers after rotation, connection pools, scheduled jobs, long-lived processes. These are the consumers that fail late, not at deploy time.

3. Set the risk tier

{{risk_tier}} drives the cadence the runbook recommends and how tight the overlap window should be. A payment-processor key earns more caution than an internal metrics token.

4. Verify with auth signals, not deploy status

A green deploy doesn't prove rotation worked. The verification section should watch authentication-success signals from each consumer. Read it carefully; it's where false confidence hides.

5. Revoke deliberately, with a window

Don't revoke the old secret the instant the new one is live. The runbook sets an overlap and a rollback window so a missed consumer surfaces while you can still recover.

Model behavior worth knowing

Claude is good at expanding {{consumers}} into a reasoned map, it'll ask, in effect, "does anything cache this?" and structure the steps around the lag. GPT-4o writes clean numbered runbooks but tends to assume instant propagation unless {{caching_notes}} forces the overlap window into the plan. Gemini handles the security framing well but sometimes collapses verification into "confirm the deploy succeeded," so restate that verification means per-consumer auth success, not pipeline status.

One pattern holds across all three: the dual-secret overlap is the safety mechanism, and models will skip it if the prompt reads as "swap the secret." Word the instruction as "both secrets valid simultaneously, then revoke the old one after verification," or the model writes a hard cutover that breaks the cached consumers.

Variables you'll set

Getting started

1. Copy the prompt skeleton into ChatGPT, Claude, or Gemini.
2. List every consumer in {{consumers}}, over-include rather than miss one.
3. Flag caching in {{caching_notes}} so the overlap window is right.
4. Run it and confirm the dual-secret overlap is in the steps.
5. Check verification watches per-consumer auth, not deploy status.
6. Follow the revocation timing and keep the rollback window open.
7. Reuse the prompt for the next credential.

Secrets that leak are worse than secrets that drift, so the scan commits for secrets prompt catches the credential before it ever reaches a repo, and the environment config review prompt catches the secret that's set in one environment and missing in another.

Rotation is one piece of release safety, so the Release Train Coordination Harness is the pack that sequences the deploy a rotation often rides alongside. Map the consumers, overlap the secrets, verify per consumer, and the rotation that used to risk a 3am page becomes a runbook you follow start to finish.