Skip to main content

Secret Rotation Runbook

This runbook covers rotating secrets for a Factory app Worker without downtime.

Principles

  • Rotate one secret at a time.
  • Deploy the new secret before revoking the old one (allows overlap).
  • Wrangler secrets are encrypted at rest; rotation is atomic per-secret.

Wrangler secret commands

Rotation procedures by secret

JWT_SECRET

JWTs already issued will be invalidated immediately. Schedule during low-traffic.

DATABASE_URL / HYPERDRIVE_*

Neon connection string rotation involves the Neon console.

STRIPE_SECRET_KEY

STRIPE_WEBHOOK_SECRET

ANTHROPIC_API_KEY / GROK_API_KEY / GROQ_API_KEY

SENTRY_DSN

Sentry DSNs are not sensitive (they’re public endpoints). Rotation is only needed if the Sentry project is being deprecated.

GitHub Actions secrets

GitHub Actions secrets (used during CI/CD) are separate from Worker runtime secrets.
Or via GitHub web: Repo β†’ Settings β†’ Secrets and variables β†’ Actions.

NPM_TOKEN (deprecated after Trusted Publishers migration)

Factory package publishing uses npm Trusted Publishers (GitHub Actions OIDC), so NPM_TOKEN is no longer required for publish workflows. Before revoking the legacy npm token, validate OIDC publish works:
  • Trigger publish workflow once and confirm logs show npm publishing via GitHub Actions OIDC trusted publisher.
  • Expected log indicators include via GitHub Actions OIDC trusted publisher and a provenance line (npm notice Provenance statement).
  • Confirm the published package version has GitHub provenance in npmjs.com package details.
After OIDC validation, revoke the legacy npm token:
  1. npmjs.com β†’ Access Tokens β†’ revoke the old automation token.
  2. Remove NPM_TOKEN from GitHub Actions secrets in this repo (and app repos using OIDC publish).

Post-rotation verification checklist

  • Worker /health returns 200
  • Auth endpoints issue and verify tokens correctly
  • DB-backed endpoints return data
  • Stripe webhook test event returns 200
  • No new Sentry errors in the 15 minutes following rotation