A clean cutover has five phases: freeze triage edits in the old tool, take a final export, import into the new one, verify with a sample and counts, and then switch gates and notifications. Keep a rollback path open until the first full business week has passed without surprises.
Before the window
Cutover is the shortest part of a migration, but it fails when preparation is thin. Have these ready.
- A mapping sheet for reasons, projects and owners
- Import scripts tested on at least two projects
- Counts from the old tool, saved: projects, open, closed and suppressed findings
- A rollback decision written down, with the owner named
- Communication sent to engineers about what will change and when
The runbook
| Phase | Action | Done when |
|---|---|---|
| 1. Freeze | Announce no new dismissals or ticket changes in the old tool | Notice posted, edits stopped |
| 2. Export | Take the final export, hash it, store it | Counts match the UI |
| 3. Import | Run the import for all projects | Import log shows no errors |
| 4. Verify | Reconcile counts, sample 20 decisions, read the orphan list | Pass rules met |
| 5. Switch | Move gates, notifications and ticket creation to the new tool | Test pull request behaves as expected |
| 6. Watch | Monitor for duplicate tickets and unexpected blocks | A quiet first week |
Freeze without freezing work
A freeze applies to decisions in the old tool, not to development. Engineers can still merge, and the old scanner can keep scanning. Anything dismissed during the window is recorded on a short list and applied by hand after the import, so no decision is lost.
Switching the gates
Gates are where a migration is felt. Run the new scanner in report only mode first, then move to blocking once the numbers look right. Compare what each tool would have blocked on the same pull requests for a week. Differences need explanations before blocking begins.
Do not enable ticket creation until the relink is complete, or you will create duplicates.
Keep the old tool running in parallel
Leave the old scanner active, read only if possible, for a defined period. It gives you something to compare when an engineer says "the old tool never complained about this". Set an end date and tell people.
Rollback criteria
Decide in advance what would send you back. Examples: a gate blocking more than an agreed share of pull requests without a clear reason, import errors affecting a large share of records, or a critical ecosystem the new tool cannot read. Write the thresholds in the plan. The decision is much easier when nobody has to improvise it.
After the switch
Record the date, the counts and the open issues in the migration record. Schedule a review at 30 days to look at suppressions that were re-triaged, orphans that remain and the first expiries coming due.
A note on Safeguard
Safeguard supports policies, gates and guardrails for pull requests, along with SBOM and dependency scanning. A free scan at gold.safeguard.sh/scan can serve as a second opinion before you switch.
Try it yourself
Open the demo and watch how a pull request gate decides whether to block a change. It is the surface your engineers will notice first after the switch.
Click through it at your own pace, or open it full screen.
Quick check
How long should the parallel run last?
Long enough to cover at least one full release cycle and one cycle of advisory updates. Many teams choose two to four weeks.
What if the export count does not match the UI?
Stop. Find the gap before importing, because you cannot reconcile later against a number you do not trust.
Last reviewed: 19 October 2026.
