The Hardest Part of a CI/CD Migration Isn’t the Technology

When I started working on moving engineering teams from EC2-based self-hosted GitHub Actions runners to GitHub-hosted runners, the first challenge was not changing workflows. It was understanding the infrastructure we already had. There was no documentation from the team that had originally built the self-hosted runner setup, so I had to investigate the environment, ask questions and speak to engineers who still knew how it worked.

That experience shaped how I think about platform migrations. Before you can decide what to move, you need to understand what exists, who depends on it and what each workload needs to keep working.

Start With Discovery, Not the Migration Plan

When infrastructure has been running for years, it is easy to assume that its design and purpose are understood. But people move teams, decisions go undocumented and configurations can outlive the reason they were introduced.

I had to build up an understanding of the existing runner infrastructure by exploring it and speaking to people with historical knowledge. That discovery was necessary before we could make sensible decisions about the migration.

If you are planning a similar change, start by reviewing the current configuration, workflows and dependencies. Talk to the people who know the system, then validate what you hear against what is actually running. Record the findings as you go. The documentation you create during discovery can also help the next person who inherits the platform.

Find Out Who is Using What

Understanding the infrastructure was only part of the work. We also needed to identify which engineering teams were using self-hosted runners, which runner groups were active, which were no longer needed and which workloads could move.

This matters because a shared platform rarely means identical usage. One team may use a standard workflow, while another depends on a particular network path or access to an internal service. A runner group that looks unused may also need validation before it can be retired.

Build an inventory of teams, runner groups and workflows, and confirm actual usage with the teams involved. This gives you a clearer view of the migration’s scope and helps you prioritise work based on evidence rather than assumptions.

Treat Exceptions as Engineering Work

Not every workload will be ready to move on the same day. One team in our migration depended on egress network connectivity to access an internal CyberArk service. The required connectivity and port were not yet in place for the GitHub-hosted runner environment, so moving that team too early risked breaking its workflows.

We left that team until later in the migration while the networking requirement was addressed. The point was not to avoid the workload, but to make sure the target environment could support what the team needed before changing its runner setup.

This is an important distinction. An exception is not necessarily resistance to change or a reason to abandon the target platform. It may be a real dependency that needs an owner, a clear resolution path and validation before migration.

For each workload that cannot move immediately, document the blocker, who is responsible for resolving it and what needs to be tested before the move can happen. That makes exceptions visible and prevents them from becoming last-minute surprises.

Plan for Adoption, Not Just Implementation

Even when the technical approach is clear, teams still need to understand what is changing and what they need to do. They have delivery commitments and existing workflows to maintain, so a migration needs communication, coordination and a way to track progress.

Make it clear which teams are ready, which need additional work and where support is available. Track blockers and follow up with teams that have not completed the transition. A single announcement is rarely enough for a change that affects many engineering teams.

The platform team’s responsibility does not end when the new environment is available. The migration is complete when teams have moved successfully, remaining exceptions are understood and the old infrastructure can be retired where appropriate.

Define What Success Looks Like

Before starting, agree how progress and completion will be measured. Useful measures may include teams migrated, outstanding technical blockers, workflows validated and old infrastructure decommissioned. If cost or operational overhead is a key reason for the migration, evaluate those outcomes too rather than assuming the expected benefits will automatically appear.

The measures should reflect the goal of the project, not just activity. Creating a new runner environment is an output. Getting teams onto it without disrupting their work is an outcome.

Five Steps to Take Into Your Next Migration

• 1. Investigate what you have inherited. Review the infrastructure and workflows,

speak to people who know the history and document what you learn.

• 2. Map teams and usage. Identify active runner groups and workloads, and validate the

inventory with the teams involved.

• 3. Identify dependencies early. Check network access, permissions and other

requirements that could prevent a workload from moving.

• 4. Give exceptions clear ownership. Record each blocker, agree how it will be resolved

and test the required changes before migration.

• 5. Measure completion. Track successful team migrations, unresolved exceptions and decommissioning, not just the deployment of the replacement platform.

The biggest lesson from this work is that a CI/CD migration is not simply a technical switch. It is a change to a system that people rely on, often in ways that are not immediately visible. Taking time to understand the infrastructure, map its users and resolve genuine dependencies makes it easier to plan the transition realistically.

The technology matters, but discovery and coordination are what help make the change work.