Why Rotate: Limiting Exposure of Long-Lived Keys
API keys: grant access to your organization's AI rules and configuration. A compromised key: allows unauthorized access to your rulesets, project assignments, and potentially your rule content. The longer a key lives without rotation: the greater the exposure window if it is compromised (leaked in a log, stored on a departed employee's machine, or exposed through a security incident). Rotation: limits this window. A 90-day rotation: means a compromised key is valid for at most 90 days before it is replaced.
The rotation challenge: the old key is used in CI pipelines, automation scripts, and developer tools across the organization. Rotating: means updating every system that uses the key. If the old key is revoked before all systems are updated: CI pipelines fail, rule sync stops, and developers are blocked. The solution: an overlap period where both the old and new keys are valid. Update all systems during the overlap. Revoke the old key only after everything is migrated.
Rotation schedule: every 90 days for standard keys. Immediately for: compromised keys (suspected or confirmed leak), keys belonging to departed employees, and keys with broader permissions than needed (rotate to a new key with reduced scope). AI rule: 'Quarterly rotation: the balance between security (shorter is safer) and operational overhead (more frequent = more work). For most organizations: 90 days is the sweet spot.'
Step 1: The Zero-Downtime Rotation Process
Phase 1 — Create the new key (1 minute): RuleSync dashboard → Settings → API Keys → Create Key. Name: include the creation date and purpose ('GHA CI - frontend - 2026-Q2'). Scope: same as the old key (or reduced if the old key was over-scoped). Copy the new key immediately. At this point: both the old key and the new key are valid. CI pipelines: still use the old key and work normally. No disruption.
Phase 2 — Update all systems (10-30 minutes): update the new key in every system that uses the old key. GitHub Secrets: Settings → Secrets → RULESYNC_API_KEY → Update value. GitLab CI Variables: Settings → CI/CD → Variables → Edit. Jenkins: Credentials → Update. Automation scripts: update the environment variable or secrets manager entry. For each system: trigger a test run to verify the new key works. AI rule: 'Update one system at a time. Verify after each update. If a system fails with the new key: investigate before updating the next system.'
Phase 3 — Verify and revoke (5 minutes): after all systems are updated: wait 24 hours (the overlap period — ensures no scheduled jobs still use the old key). After 24 hours: verify no requests are using the old key (check the key's last-used date in the dashboard). If last-used is before the rotation: safe to revoke. Revoke: Settings → API Keys → [old key] → Revoke. The old key: immediately invalid. All systems: already using the new key. Zero downtime.
You updated GitHub Actions, GitLab CI, and Jenkins. But: a scheduled cron job on a separate server also uses the key — you forgot about it. Without overlap: you revoke the old key. The cron job: fails silently until someone notices days later. With 24-hour overlap: the cron job runs successfully with the old key during the overlap period. You: notice the old key was used (check last-used in the dashboard). You: update the cron job. Then revoke. The overlap: catches the systems you forgot.
Step 2: CI-Specific Rotation Steps
GitHub Actions: Settings → Secrets and variables → Actions → RULESYNC_API_KEY → Update secret. The update: takes effect on the next workflow run. No workflow file changes needed (the secret name stays the same — only the value changes). Verify: trigger a manual workflow run or wait for the next PR. The CI log: should show successful RuleSync operations with no authentication errors.
GitLab CI: Settings → CI/CD → Variables → Edit RULESYNC_API_KEY → paste the new value. If the variable is masked and protected: the new value inherits the same settings. Verify: trigger a pipeline run. The pipeline: should complete the RuleSync steps without errors. For multiple projects sharing the same key (group-level variable): update once at the group level — all projects inherit the new value immediately.
Multiple CI platforms: if the key is used across GitHub Actions, GitLab CI, and Jenkins: update all three before revoking the old key. The 24-hour overlap: gives time to update all platforms even if they are managed by different teams. Checklist: list every system that uses the key. Update each one. Check it off. Revoke only after all are checked off. AI rule: 'The checklist prevents: revoking the old key while one system still uses it. A missed system: causes CI failures. The checklist: ensures completeness.'
The temptation: update 3 out of 4 systems and revoke ('I will update the 4th later'). The reality: you forget the 4th. Its next CI run: fails with 401. The developer using that system: files a support ticket. Investigation: 30 minutes to trace the auth failure to the revoked key. Fix: create a new key, update the 4th system. Total disruption: 1 hour. The rule: update ALL systems, verify ALL systems, THEN revoke. The checklist: ensures 'all' means all.
Step 3: Automating and Scheduling Rotation
Rotation reminders: set a calendar reminder 90 days after each rotation. The reminder: 'Time to rotate RuleSync API keys. Checklist: [link to the rotation checklist].' For organizations with multiple keys: maintain a key inventory spreadsheet (key name, purpose, creation date, next rotation date, responsible person). The inventory: reviewed monthly. Keys approaching their rotation date: flagged for the responsible person.
Automated rotation (advanced): for organizations that want fully automated rotation: use a secrets rotation service (AWS Secrets Manager rotation, HashiCorp Vault dynamic secrets). The service: creates a new key, updates the secret in CI, verifies, and revokes the old key — all automatically on a schedule. This automation: eliminates the manual rotation process entirely. The setup: 2-4 hours initially. The ongoing effort: zero (fully automated).
Key hygiene audit: during rotation, audit all active keys. Questions: is each key still needed (the automation it serves is still running)? Is each key correctly scoped (not over-permissioned)? Are any keys unused (last-used date is more than 90 days ago — revoke)? The rotation: a natural opportunity to clean up key hygiene. AI rule: 'Rotation is both security (new key) and hygiene (audit and clean up). Combine both activities in the same process.'
During the rotation: you review all active keys. Discovery: a key named 'test-key-march' was created 8 months ago. Last used: never. Purpose: unknown. This key: a forgotten test key with potentially broad permissions. Action: revoke immediately. Without the rotation audit: this key persists indefinitely — an unused credential with unknown permissions. The rotation: forces a periodic review that catches and cleans up orphaned keys.
API Key Rotation Summary
Summary of rotating RuleSync API keys.
- Schedule: every 90 days. Immediately for: compromised keys, departed employees, over-scoped keys
- Process: create new key → update all systems → verify → wait 24 hours → revoke old key
- Zero downtime: both keys valid during the overlap period. No system uses the old key when it is revoked
- GitHub Actions: update secret value. Same secret name. Takes effect on next workflow run
- GitLab CI: update variable value. Group-level: one update serves all projects
- Checklist: list every system using the key. Update each. Check off. Revoke after all checked
- Automation: secrets rotation services (AWS, Vault) for fully automated rotation. 2-4 hour setup
- Hygiene: during rotation, audit all keys. Remove unused. Reduce over-scoped. Clean up the inventory