Migrate in a parallel run, not a cutover weekend. Export your history and exceptions first, stand up the new platform beside the old one, recreate policies, compare results on a sample, then move teams in waves. Retire the old system only after an audit style question can be answered from the new one.
Start with what you must not lose
List the assets that have value beyond the tool itself.
- Exceptions and their reasons. These are decisions, and re-deciding them wastes weeks.
- Dated SBOMs and scan history. Evidence for past releases.
- Policies and gate rules. Including who approved them.
- Ownership mappings. Which person or team owns which repository.
- Integration settings. CI hooks, ticketing links, chat alerts.
Export all of these in files you can read without the old tool. SBOMs in CycloneDX or SPDX are portable by design. Both are published open standards, and SPDX is recognized as ISO/IEC 5962:2021.
The migration steps
- Freeze the baseline. Record counts of repos, open findings by severity, and open exceptions. This is your before picture.
- Export. Pull SBOMs, exceptions, and policies. Store them with a date.
- Connect the new platform read only. Start with the same pilot repos you would use for a fresh evaluation.
- Recreate policy. Rewrite rules rather than copying names blindly. Different tools define severity and reachability differently.
- Compare results. On ten repos, diff component lists and findings, and explain every difference.
- Import exceptions. Set expiry dates. An old exception should not become permanent by migration.
- Run in advise mode in the new tool while the old one still enforces.
- Cut over in waves. One team at a time, with a named contact.
- Archive the old data. Keep exports for as long as your retention policy requires.
- Cancel the old tool after an audit style spot check passes.
Risks and how to cover them
| Risk | Cover |
|---|---|
| Gap in enforcement during cutover | Never turn gates off in the old tool until the new gate is live for that team |
| Duplicate alerts annoy developers | Mute old alerts per team as each wave moves |
| Policy meaning shifts | Test each rule on a known bad sample |
| Lost audit trail | Keep dated exports of the old system |
Timing
Avoid migrating near a major release, an audit window, or a holiday freeze. If a customer has requested evidence for a past period, export that evidence first.
Communicate
Tell developers what changes in their pull request, what stays the same, and who to ask. Most migration friction is surprise. A short note with a screenshot of the new comment format prevents a week of questions.
A worked example
Take a hypothetical company moving from one platform to another across 120 repositories and eight teams. The program lead starts by building a migration sheet with one row per team.
The baseline shows 120 repositories, a few hundred open findings, and about thirty exceptions. The lead exports SBOMs for the last four releases of each product into a dated folder. She exports the exception list, noting for each the owner, reason, and expiry. She finds that eleven exceptions have no expiry, and she sets one before importing.
In wave one, two friendly teams connect their repositories to the new platform, with gates in advise mode. The old platform still enforces. Results diverge on two repositories. The team reconciles and finds that the new platform treats a development only dependency differently. They adjust a rule. In wave two, four teams move. The old gate is turned off for each only after the new gate has produced a week of agreed results. In wave three, the last two teams move, including one with a regulated product, which keeps both systems for an extra release cycle.
The old tool is cancelled after an audit style spot check: someone asks for the scan history of a release from two quarters ago, and the exported archive answers it.
Migration sheet columns
| Team | Repos | Owner | Wave | Old gate off date | Notes |
|---|---|---|---|---|---|
| Payments | 14 | Named person | 3 | Extra release cycle | |
| Web | 22 | Named person | 1 |
Update it in the weekly meeting. It becomes your status report.
Pitfalls specific to migration
- Severity drift. A medium in one tool may be a high in another. Review the mapping before you set blocking rules.
- Alert storms. The new tool may re-report items already accepted. Import exceptions before you turn on notifications.
- Hidden dependencies on the old tool. Check for scripts, dashboards, or compliance reports that read from the old system and will break.
- Retention gaps. Confirm that exported data covers the period your policies require.
- Credentials left behind. Revoke the old tool's tokens and app installs when its last team moves.
Checklist for the last week
- Confirm all gates are live in the new tool.
- Remove old integrations from every repository.
- Revoke old credentials and confirm in the source host's audit log.
- Store exports with an index file describing what each contains.
- Ask the old vendor to confirm data deletion where your policy requires it.
- Update runbooks and onboarding docs with the new tool's names.
Try it yourself
Click through it at your own pace, or open it full screen. Open the demo and watch how a finding's status changes over time. A migration should preserve that history, not reset it.
Safeguard keeps a shared record with SBOM and dependency scanning, policies and gates, and compliance and evidence automation. Try the free scan at gold.safeguard.sh/scan to compare your inventory before you commit to anything.
Quick check
How long should the parallel run last?
Long enough to cover at least one full release cycle for the pilot teams.
Can I import another tool's SBOMs?
If they are in a standard format such as CycloneDX or SPDX, usually yes. Confirm with a test file.
Should we migrate exceptions as they are?
Import them with an owner and an expiry date. Do not let old open ended exceptions become permanent.
Sources
Last reviewed: 19 October 2026.
