To retire an approved package, mark it deprecated, block new use, find every current user, offer a replacement and migration help, set a stop date, then remove it from the registry and list. Skipping the usage report is how retirements cause outages.
Reasons to retire
A package may be abandoned, relicensed, replaced by a better supported option, or found to carry a risk you cannot fix. Whatever the reason, the process is the same, and the urgency varies.
The steps
- Decide and record the reason, the date and the owner of the retirement.
- Set the status to deprecated in the approved list. New projects can no longer add it, and the intake form points to the replacement.
- Produce a usage report from SBOMs, lockfiles and proxy logs: which products and versions use it, and which teams own them.
- Name a replacement or an approved approach. If there is none, say so, and decide whether the work is a rewrite.
- Notify owners with the stop date and what support they get. Give a realistic window and keep it.
- Track progress weekly and escalate stragglers to their leaders, not to individual developers.
- At the stop date, block the package at the proxy for new downloads, except for listed exceptions.
- After the last user moves, remove it from the list and keep the record.
Urgency levels
| Situation | Window |
|---|---|
| Confirmed malicious or compromised | Immediate block, treat as an incident |
| Serious unfixed vulnerability, actively exploited | Days, with compensating controls |
| Abandoned, no known exploit | Months, planned in normal work |
| Replaced by a preferred option | A release or two, tracked in the roadmap |
Define these categories in advance so you do not argue about urgency during the event.
Common mistakes
- Blocking the proxy before the usage report, which breaks builds without warning.
- Forgetting transitive users. A package you retire may still arrive through another dependency.
- Not handling cached copies. Remove it from caches and mirrors when the stop date passes, or it stays available.
- Leaving old container images that include it. Rebuild and rotate images on a schedule.
Evidence
Keep the decision, notice, usage report and completion date together. If an auditor or customer asks how you manage end of life components, this is a complete answer.
Try it yourself
Click through it at your own pace, or open it full screen. Look at how findings are tracked from detection to closure, which is the same loop a retirement needs.
Quick check
Can we just delete it from the registry?
Not before you know who uses it. Run a usage report first, then block new downloads at the stop date.
What about transitive users?
Check the full resolved tree in SBOMs, not only manifests, and engage the owners of the parent packages.
Safeguard scans dependencies and builds SBOMs, runs reachability analysis, and applies policies and gates on pull requests, so the rules in this post can be checked automatically. Autonomous fix PRs are off by default, with every category on Manual. You can run a free scan at gold.safeguard.sh/scan.
Last reviewed: 19 October 2026.
