Create the new token before you touch the old one, run both for an overlap window, update every secret store, test with one canary pipeline, then revoke the old token and watch for 401 errors. Never revoke first. Set an expiry on the new token so the next rotation is already scheduled.
Why rotations break builds
Most failed rotations share one cause: the old token was revoked before every consumer had the new one. Tokens are copied into more places than anyone remembers: CI secrets, runner images, developer machines, scripts, mirror upstream settings, and container build arguments. Revoke early and one forgotten copy fails at 3 a.m.
What the registry lets you do
Using npm as the example, the access token documentation says granular tokens can be given an expiration date at least one day in the future, can be limited by package, scope and IP range, and can be read only. An account can hold up to 1000 granular tokens. That headroom is what makes an overlap possible: you can hold the old and new tokens at the same time without deleting anything. Check the limits for your own registry.
The rotation steps
- Inventory the consumers. Search your repositories, CI settings and secret stores for the token name or the registry host. Write the list down.
- Create the new token. Same scope, read only if the old one was read only, with an expiry date. Name it with the date so it is obvious later.
- Update the secret stores. Replace the value in each place. Do the least critical pipelines first.
- Run a canary. Pick one low risk pipeline and one clean install. Confirm that it authenticates with the new token, not a cached credential from an earlier run.
- Wait through an overlap window. Keep the old token alive for a day or a full cycle of your scheduled jobs, so nightly and weekly pipelines also run with the new one.
- Watch the logs for 401s. A 401 from the old token tells you a consumer was missed. A 401 from the new one tells you a mistake in the new value. See registry errors in CI.
- Revoke the old token. Only after the overlap window and a quiet log.
- Record it. Note the date, the owner, the consumers and the next expiry.
A timing table
| Step | When | Rollback if it fails |
|---|---|---|
| Create new token | Day 0 | Delete it, nothing else changed |
| Update secrets | Day 0 to 1 | Put the old value back |
| Canary run | Day 1 | Fix the value, repeat |
| Overlap window | Day 1 to 3 | Old token still works |
| Revoke old | Day 3 or later | Create another new token |
Rotating after a leak is different
If a token leaked, skip the overlap. Revoke first, accept the breakage, and fix consumers quickly, because the leaked token is already in someone else's hands. The checks are in leaked registry token: what to check on npm and PyPI. Planned rotation and incident rotation are two procedures. Write both down.
Make the next rotation cheap
- Use a service account so the token does not depend on one person, as discussed in should every pipeline share one registry read token.
- Prefer short lived credentials where your CI and registry support them. See OIDC vs static credentials in CI.
- Keep one place that mints or stores the token, so you update one value, not twelve.
Where Safeguard fits
Rotation reduces the window in which a stolen credential works. Safeguard's asset discovery and SBOM and dependency scanning help you find which repositories and pipelines depend on a registry, so the consumer list in step one is not a guess.
Quick check
How long should the overlap window be?
Long enough for your slowest scheduled pipeline to run once. For many teams that is a few days. Use your own schedule to decide.
Should I rotate on a fixed schedule?
A schedule is useful, and an expiry on each token enforces it. Rotate immediately if you suspect exposure.
Sources
Last reviewed: 19 October 2026.
