The Illusion of "Just a Migration"

The Repository Myth

When people talk about migrating to GitHub, they usually talk about repositories. How many repositories need to be moved? How much history must be preserved? How long will it take?

Those questions matter, but they rarely determine whether a migration succeeds. The reality is that source code is usually the easiest part of the journey. What makes migrations difficult is everything around the code.

A modern development platform accumulates years of decisions. Pipeline templates reference other repositories. Build systems depend on internal package feeds. Security controls evolve differently across teams. Developers create workarounds that slowly become business-critical without anyone noticing.

None of these things appear in a repository inventory. Yet they are often what determines the complexity of a migration.

Many organizations start their journey believing they are moving repositories. What they are actually moving is an ecosystem of processes, automation, integrations, permissions, infrastructure and institutional knowledge.

That distinction changes everything.

Why Organizations Migrate

Organizations rarely decide to migrate development platforms without a reason.

Sometimes the driver is consolidation after an acquisition. Sometimes it is a desire to standardize engineering practices across multiple business units. In other cases, the motivation is stronger governance, improved developer experience, or access to new capabilities such as GitHub Copilot and GitHub Advanced Security.

The business reason may differ, but the challenge remains remarkably similar. A migration is rarely about replacing one repository hosting platform with another. It is about changing the environment where software is built, reviewed, secured and delivered.

That is why successful migrations require both technical and organizational planning.

Why Every Migration Is Different

Organizations often ask for benchmarks. How long did a previous migration take? How many repositories were involved? How many developers were affected?

Those numbers provide context, but they rarely predict the effort required for another organization. We have seen environments with thousands of repositories that were relatively straightforward to migrate. We have also seen environments with only a few hundred repositories that required significantly more effort.

Complexity is rarely driven by volume alone.

The number of integrations, the maturity of engineering practices, the level of standardization and the amount of platform customization usually have a far greater impact than repository count.

This is why migration planning cannot rely solely on inventory statistics. The most important complexity is often hidden beneath the surface.

The Hidden Cost of Success

There is an interesting paradox in long-running engineering organizations. The more successful a platform becomes, the harder it often is to migrate.

Successful platforms accumulate automation, deployment workflows, security controls, integrations, and operational knowledge. Each decision makes sense at the time it is made. Years later, those decisions form a highly interconnected ecosystem.

Migration teams are not simply moving source code from one platform to another. They are untangling years of accumulated knowledge, assumptions and dependencies. This is why migrations frequently become discovery exercises. Organizations often learn more about their environment during migration than they did during years of normal operation.

The Analysis Trap

Faced with a migration involving hundreds or thousands of repositories, the natural instinct is to analyze everything first. Build a complete inventory. Document every repository. Understand every dependency. Create the perfect plan. The idea sounds reasonable. The problem is that analysis has a shelf life.

While a migration team is documenting the environment, the environment continues to evolve. New repositories appear. Pipelines change. Teams reorganize. Integrations are added or removed. By the time the analysis is complete, portions of it are already outdated. Large-scale migrations rarely benefit from attempting to understand everything upfront.

A more effective approach is incremental discovery. Analyze a manageable scope, execute the migration, learn from the results and use those lessons to improve the next wave. The goal is not perfect knowledge. The goal is enough knowledge to move forward safely.

The Separation Strategy

One of the most common questions during migration planning is whether repositories and pipelines should be migrated together. At first glance, doing both simultaneously appears efficient. In practice, combining the two often increases risk.

Repository migration and pipeline migration have very different complexity profiles. When they are tightly coupled, a problem in one area can block progress in the other. Separating the workstreams creates flexibility. Repositories can be migrated and stabilized while pipeline migrations continue independently. This allows teams to adopt GitHub without waiting for every deployment workflow to be rewritten. The exact transition model differs from organization to organization, but the principle remains consistent.

Do not allow pipeline complexity to dictate repository migration timelines. Keeping those concerns separate significantly reduces operational risk.

CI/CD Is Usually the Real Project

Repository migration receives most of the attention. CI/CD migration usually consumes most of the effort.

Modern pipelines are no longer simple build scripts. They coordinate testing, security scanning, compliance controls, infrastructure provisioning, deployments, approvals, artifact management and reporting. Over time, these workflows become deeply embedded in daily operations. Migrating them requires more than translating syntax from one platform to another. It requires understanding intent.

Why does this workflow exist? Which controls are mandatory? Which steps are historical artifacts that no longer provide value?

The answers to those questions often matter more than the technical implementation itself. Organizations are often surprised by this reality. Repository migration is usually predictable and highly automatable. Pipeline migration is where complexity, risk and effort tend to concentrate.

The Surprises Nobody Warns You About

Every migration uncovers unexpected challenges. Submodule dependency chains force repositories to be migrated in a specific order. Undocumented webhooks suddenly become visible when they stop working. Repositories appear without clear ownership because the original teams no longer exist. Infrastructure assumptions turn out to be incorrect.

Other surprises have less to do with technology and more to do with timing. Access provisioning takes longer than expected. Validation activities take longer than expected. And again and again, team availability becomes a larger constraint than technical complexity.

None of these challenges are particularly unusual. In fact, they are so common that they should be considered normal. The organizations that experience the smoothest migrations are not the ones that avoid surprises. They are the ones that expect surprises and plan accordingly.

The Wave Model

Large migrations are rarely successful when executed as a single event. Breaking the migration into smaller waves creates control, visibility and learning opportunities.

A pilot wave allows teams to validate tooling, permissions, communication processes, rollback procedures and success criteria before scaling further. Subsequent waves benefit from the lessons learned earlier in the program. Patterns emerge. Reusable solutions appear. Teams become more familiar with the target platform. Operational confidence grows.

The result is not simply a migration process that scales. It is a migration process that improves as it progresses.

Practical Insights

Every migration teaches something new, and we continue to learn with each one. Still, a few lessons appear so consistently that they are worth highlighting on their own.

The first concerns analysis. Knowing how many repositories exist is not the same as understanding them. What matters is the relationships between them. Which repository is a submodule, and which one depends on submodules of its own? Which repositories carry pipelines that must be migrated alongside the code? What does the dependency tree actually look like? The full picture is impossible to know at the start, and some dependencies will only reveal themselves when they block you. That is precisely why it must stay in mind throughout the program. The aspects you can uncover early become valuable inputs for planning and for organizing waves.

The second concerns continuity. When a repository moves, the work around it cannot stop. Pipelines must keep running, deployments must keep happening, and the wider system should feel no disruption. This usually comes down to a choice between mirroring and rewiring. Rewiring introduces changes to the original environment, but it tends to be more reliable because it removes the burden of keeping two instances in sync. Mirroring can be the better option when the original environment must remain untouched, or when teams want room to test rewritten pipelines before committing to the final migration. Neither approach is universally correct. The right choice depends on how much risk the original environment can absorb.

The third concerns people. Dependencies are not only technical. A high number of them makes it difficult to keep every team and every engineer moving together. Progress in one repository often depends on progress in another, and that coordination cannot be improvised. A solid plan matters here, but so does the way the work is carried out. Migrations succeed in collaborative environments, not in isolation.

The fourth concerns untangling. Pipeline dependencies rarely come apart cleanly. Sometimes they can be resolved by refactoring shared logic into reusable components. Sometimes the answer is a proper artifacts management. And sometimes there is no way around moving the dependent pieces together. Whichever path applies, the same principle holds. Make sure you can test the outcome before you make the move.

What Organizations Learn During Migration

One of the most valuable outcomes of a migration is not the migration itself. It is the visibility gained during the process.

Migration programs expose duplicate workflows, inconsistent practices, governance gaps, outdated dependencies and operational assumptions that have accumulated over time. In many cases, organizations discover opportunities for improvement long before the final repository is migrated. The process also creates opportunities to build internal capability.

Engineering teams gain experience with modern CI/CD practices. Shared workflow patterns emerge. Reusable components reduce duplication. Knowledge becomes easier to share across teams.

Migration becomes a catalyst for standardization, not through enforcement, but through visibility and collaboration.

What Happens After Go-Live

The final cutover is often treated as the finish line. In reality, it is closer to the starting line.

Once repositories and pipelines have been migrated, organizations begin the next phase of adoption. Teams refine workflows. Governance models mature. Security controls evolve. New platform capabilities become available.

The way an organization uses GitHub six months after migration is often very different from how it used GitHub on day one. This is a sign of success. Migration should create a foundation for continuous improvement rather than a fixed end state.

Measuring Success

A migration can complete on schedule and still fail to deliver value. Success is not measured by the number of repositories migrated or pipelines converted.

Those are outputs. The more meaningful indicators appear later.

How quickly can new developers become productive? Has security improved? Are engineering standards easier to maintain? Are teams spending less time managing delivery infrastructure and more time building products?

Those outcomes provide a far more accurate measure of success than migration statistics alone.

Final Thoughts

The technical act of moving repositories from one platform to another is only one part of a migration. The larger challenge is understanding and evolving the engineering ecosystem that surrounds those repositories.

That ecosystem includes people, processes, automation, governance, security and culture. Organizations that recognize this early are usually the ones that achieve the strongest results.

The goal is not simply to arrive on a new platform. The goal is to create a better software delivery environment than the one that existed before the migration started.