Move existing services in waves, ordered by risk and effort, using the same few controls the template gives new services. Start by adding visibility, then automation, then enforcement. Do not try to rebuild every repo from the template.
Why retrofits are different
A template only reaches repos created after it exists. Most of your risk sits in services that are already running. Regenerating them from a template is rarely practical, because they have history, custom build steps and owners with other priorities. The Backstage documentation describes software templates as loading code skeletons, templating in variables, and publishing to a location such as GitHub or GitLab. That is a creation flow, not a migration flow.
So treat retrofit as a separate program with its own plan.
The four waves
| Wave | Goal | What changes in the repo |
|---|---|---|
| 1. See | Know what exists | Register service and owner in the catalog, generate an SBOM, no blocking |
| 2. Automate | Reduce toil | Add update automation config and a scan on pull requests in report mode |
| 3. Enforce | Stop new debt | Turn on the merge gate for new high severity findings |
| 4. Clean | Pay down old debt | Fix existing findings by priority, with deadlines set by tier |
Notice that wave 3 blocks only new problems. Blocking on old findings on day one makes every pull request fail and teaches teams to resent the program.
How to choose who goes first
- Internet facing services and anything handling sensitive data.
- Services with many dependencies or old runtimes.
- Services with active development, where the change cost is low.
- Low change, low risk services last, with a documented exception if needed.
Pair each wave with a date range and a named owner on the platform side. Publish the schedule so no team is surprised.
Make the change small for each team
The best retrofit is a pull request the team can merge in ten minutes. Generate it for them in bulk: a lockfile check, an update config, a CI step. Include a short note explaining what it does and how to ask for help. Teams that must write the change themselves will postpone it.
Where a service uses an unusual build, do not force the standard step. Record the gap, offer a manual path, and revisit later. A tracked exception beats a silent skip.
Measure it
Track the number of services at each wave, and how long the median service takes to move. Share the chart monthly. The measures in how to measure paved road adoption for security apply here too.
Keep new services from slipping back
Once a service reaches wave 3, add a catalog check that flags any repo that loses its CI scan or update config. Without that, drift undoes the work within a few quarters.
Where Safeguard fits
Safeguard's asset discovery helps find repositories and services you did not know about for wave 1, and its SBOM and dependency scanning, policies and gates cover waves 2 and 3. Reachability analysis helps order wave 4. Try a free scan at gold.safeguard.sh/scan.
Try it yourself
Open the monitoring demo and see how a service stays tracked after merge, which is what wave 1 visibility sets up.
Click through it at your own pace, or open it full screen.
Quick check
Should we block on all existing findings in wave 3?
No. Block on new high severity findings first, and schedule cleanup of old ones separately.
Can we regenerate old services from the template?
Rarely. Templates are creation flows. Bulk pull requests that add the same controls are usually more practical.
Sources
Last reviewed: 19 October 2026.
