A good rollback plan has four parts: a tag on the last commit that used the old tooling, an old build you can still run for one release, written triggers that say when to roll back, and a rehearsed rebuild from the old lockfile. Write it before the cutover, not during the incident.
Why plan this at all
A package manager migration changes how every dependency is resolved and installed. Most problems show up fast, in tests. A few show up late: a platform specific package missing in production, a changed install script policy, a registry setting that no longer applies. When the problem shows up late, you want a calm way back.
The Gradle migration guide advice to keep the old and new builds side by side until confident is the foundation, because you know the old build works.
The plan
- Tag the last commit that uses the old package manager and lockfile.
- Keep the old build definition runnable in the repository for the first release after cutover, even if CI no longer runs it by default.
- Record the exact old tool version, for example in the notes of the tag.
- Define rollback triggers (table below).
- Rehearse: from a clean checkout of the tag, build and run the tests. A rollback you never tried is a guess.
- Name who decides, and who executes.
Rollback triggers
| Trigger | Example |
|---|---|
| Runtime failure | Missing module or native package in production |
| Version difference found late | A downgrade that reintroduces a known advisory |
| Registry or auth failure | Private packages resolving from the wrong host |
| Build time or cache problem | CI cannot install reliably |
| Security policy gap | Install scripts now run, or no longer run, where you expected |
What rolling back means
It means building from the tagged commit, not hand editing the new lockfile. Deployed artifacts built by the old process can be redeployed if you keep them. Keep the previous release's artifacts and image tags for at least one cycle. See rebuild from lockfile after a bad dependency update.
Who needs to know
Tell the on call engineer and the release manager that a migration is in flight, which tag is the rollback point, and what the triggers are. A rollback plan that only its author knows is not a plan. Put the one page summary in the pull request description and the team channel so it can be found at two in the morning.
Roll forward is also a plan
Sometimes the fix is faster than the rollback. Decide in advance how long you will try to roll forward, for example a fixed number of hours, before reverting. Without a limit, teams stay half migrated.
After the migration holds
When a full release has shipped and no trigger fired, remove the old build files in a separate pull request and delete the plan's temporary pieces. See delete the old lockfile after a package manager switch. For the general idea in scanners, see rollback criteria for a scanner migration.
Safeguard's continuous monitoring and dependency scanning can show whether new findings appeared after the cutover. A free scan is at gold.safeguard.sh/scan.
Quick check
How long keep the old build runnable?
At least through the first release from the new setup, then remove it in a separate change.
Should rollback edit the new lockfile by hand?
No. Rebuild from the tagged commit so the lockfile and tooling match.
Sources
Last reviewed: 19 October 2026.
