Why plan before you move anything
Moving Git repositories from Azure DevOps to GitHub is mechanical and well supported. The surprises arrive afterwards: a build that no longer runs, a board nobody can find, a pull request rule that behaves differently, a deployment credential that was never documented. A migration plan exists to find those before your engineers do.
This page describes the planning work we do as part of our Azure DevOps consulting. The execution detail for the move itself is on our page about Azure DevOps to GitHub migration; here we focus on the decisions and sequencing that make it succeed.
What a good plan contains
- A full inventory with active and unused items separated.
- A target model for GitHub organisations, teams, repositories and rules.
- A decision per component: move, rebuild or retire.
- Waves, with a pilot, freeze windows and owners.
- Exit criteria and a rollback route per wave.
- A communication plan and short training material.
How it works in practice
Discovery
We start with what exists. For each Azure DevOps project: repositories and their last activity, branch policies, pipelines (YAML and classic), variable groups, service connections, Boards process templates, extensions, webhooks and service hooks, and the users and groups with their permissions. Archived or untouched repositories are flagged, since moving them is rarely worth the effort.
Deciding what each part becomes
| Azure DevOps | Typical GitHub target | Effort |
|---|---|---|
| Git repositories | GitHub repositories | Low |
| Branch policies | Branch protection or rulesets | Medium |
| YAML pipelines | GitHub Actions workflows | Medium to high |
| Classic release pipelines | Workflows with environments | High |
| Variable groups, Key Vault links | Secrets, variables, OIDC to the cloud | Medium |
| Service connections | OIDC federation or scoped credentials | Medium |
| Azure Boards | GitHub Issues and Projects, or keep Boards | Varies |
| Azure Artifacts | GitHub Packages or keep Artifacts | Medium |
| Permissions | Teams and repository roles | Medium |
Two rows deserve attention. Pipelines are not converted automatically in any way that produces a pipeline you would want to maintain, so we rebuild them around reusable workflows and treat the old YAML as a requirements document. Classic release pipelines carry approvals, gates and stage logic that must be expressed as environments and protection rules. Our page on deployment environments and approval gates shows the Azure DevOps side of what needs to be recreated.
Migrating repositories
GitHub provides a CLI extension and an importer service for moving repositories from Azure DevOps, including pull request history in supported cases. A typical dry run looks like this:
gh extension install github/gh-ado2gh
gh ado2gh migrate-repo \
--ado-org my-ado-org --ado-team-project shop \
--ado-repo web --github-org my-gh-org --github-repo web
Treat flags and capabilities as something to check against current documentation before the real run, since the tooling evolves. We always rehearse on a copy, compare branches and tags, and confirm that large files and submodules behaved.
Work tracking
If you use Azure Boards heavily, with custom process templates, area paths and queries, mapping to GitHub Issues is not one to one. The options are to keep Boards and link it to GitHub, to move to Issues and Projects, or to start fresh with only open items. We help you choose using your reporting needs. See Azure Boards configuration for what is being replaced or retained.
Identity and access
Authentication moves to GitHub accounts, ideally with single sign-on through your identity provider. Permissions are rebuilt using teams and repository roles rather than copied user by user. For cloud access, we replace stored secrets with OIDC federation, so workflows get short-lived credentials. This is a security improvement worth taking during the move.
Waves and cutover
A pilot team goes first, usually a team that is open to feedback and has moderate release risk. Each wave has a freeze window, a final sync, a switch of remotes and a read-only flag on the old repository. Developers need to update their local remotes, so we provide the exact commands.
Communication and the first week after cutover
Most support requests after a wave are predictable: “my local clone points at the old URL”, “where did my pipeline go” and “why can I not push to main”. We write the answers before the wave starts and post them where developers already look. A named person watches the first week, collects recurring questions and updates the guide. It is also worth agreeing in advance who can approve exceptions to branch protection during that week, so urgent fixes are not blocked while rules are still being tuned.
Decisions and trade-offs
Full move or hybrid? A hybrid keeps Boards or Artifacts in Azure DevOps and moves code and CI to GitHub. It reduces change but leaves two systems.
Rebuild pipelines now or after the move? Moving repositories first while pipelines still run in Azure Pipelines is possible and reduces risk, because Azure Pipelines can build GitHub repositories. The cost is a longer period of two systems.
Preserve history or start fresh? Git history is kept. Pipeline history and work item detail are costlier to preserve, so ask what an auditor or developer will actually need.
When not to migrate. If no one can say what problem GitHub solves for you, pause. Migration is a project with real cost, and it should be justified by consolidation, developer experience, security tooling or ecosystem needs.
Common failure modes
- Underestimating pipelines. The code moves in a day and the builds take months.
- Forgotten integrations. Webhooks and service hooks fire into nothing.
- Permission drift. Everyone becomes admin to avoid friction.
- Two sources of truth. Developers push to the old repository after cutover.
- No communication. Teams find out on the day.
Delivery and handover
The plan you receive covers the inventory, target model, component mapping, wave schedule, risk register, rollback steps, communication drafts and a post-migration checklist. If you want us to run the migration as well, it is scoped from that plan. To start, book a consultation.
How to tell it is working
The pilot completes without unplanned work, each wave meets its exit criteria, builds are green on the new platform, old repositories are read-only on schedule, and developers stop asking where things went.