Migrate from Azure DevOps to GitHub – what you…

Developers love GitHub, and I do to! However, migrating from one platform to another is akin to orchestrating a complex dance. The rhythm of code, the choreography of pipelines, and the harmony of collaboration—all must align seamlessly. But beneath the surface lies the intricate steps: data mapping, permissions, and legacy dependencies. As the curtain rises, let us delve into the intricacies of this migration journey, where every line of code carries the weight of history, and every commit echoes the promise of a new beginning.

I’ve been apart of this project before, and now I find my self in the same situation. The goal is the same, but not all solutions are identical. You will need to adjust your tasks to fit your company’s situation. But in this blog post, I will outline what you need to know when migrating from Azure DevOps to GitHub.

GitHub for organization and GitHub enterprise.

GitHub enterprise is probably what you’re looking for. You can get some things done with an Organization only, but if you want to use some security features, let’s say, branch policies for internal repositories, you’re forced to go the enterprise route.

GitHub Organizations are well-suited for open-source projects, small teams, or individual developers.

• They provide a collaborative space for managing repositories, teams, and access permissions.
• Features include team-based access control, issue tracking, and project management.
• Ideal for community-driven development and public repositories.

GitHub Enterprise caters to larger organizations and enterprises.

• It offers enhanced security, scalability, and administrative controls.
• Features include advanced auditing, single sign-on (which you want), and enterprise-grade support.
• Perfect for companies with (any) compliance requirements and a need for robust infrastructure.

GitHub Enterprise – account types

Time to chose how accounts are managed. In DevOps you probably used your company’s existing accounts synced with Entra ID. For GitHub you have two options.

Individual accounts using SAML: These are user accounts that are linked to an identity provider (IdP) using Security Assertion Markup Language (SAML). Users can sign in to GitHub Enterprise Cloud with their existing credentials with a linked account to your identity provider, most likely Azure Entra ID.

The other option is Enterprise managed users: Here the user accounts are provisioned an managed through the IdP. Of course this is what you want, right. Full control! However, in both projects we ended up with option 1, individual accounts with SAML. What you do comes down to whether you want to favor developer experience a bit more than full control and central management.

Enterprise managed users are totally blocked from any collaboration outside your enterprise. This means creating issues on a public repo, etc. I really hope GitHub will change this, because what we actually want is both!

Migrating repositories

Let’s delve in to the more technical side of things. You want your repositories moved from DevOps to GitHub. And that is pretty damn simple, possibly the easiest part of the whole project as both is using Git as the underlying technology.

If you only have a handful repo’s a simple git clone can do the job. But most likely, you want to do a bit more, and if you are like me, working as a platform engineer or similar, you probably would like to streamline the process, and have each repository set up with some baseline settings. All this will require some scripting.

Enter GitHub CLI and ADO2GH extension despite having a super annoying limitation requiring personal access tokens (PAT) for bot DevOps and GitHub, I still think this is you best option. I spent a few hours trying to find out how to use GH CLI with an application, but without luck. Considering this is a time limited project, using a PAT from a service account (will consume a license) is acceptable.

Our solution for migrating repositories is a workflow in GitHub developers can run. Below is an example on the workflow and the PowerShell migration script.

	param(
	[Parameter(HelpMessage="The Azure DevOps organization.")]
	[string]$adoOrg = "Adatum",
	[Parameter(Mandatory=$true, HelpMessage="The Azure DevOps team project.")]
	[string]$adoTeamProject,
	[Parameter(Mandatory=$true, HelpMessage="The Azure DevOps repository.")]
	[string]$adoRepo,
	[Parameter(HelpMessage="The GitHub organization.")]
	[string]$githubOrg = "Adatum",
	[Parameter(HelpMessage="The GitHub repository.")]
	[bool]$lockAdoRepo = $false,
	[Parameter(HelpMessage="Repository owner.", Mandatory=$true)]
	[string]$repoOwner
	)
	# Use the Azure DevOps repository name as the GitHub repository name
	[string]$githubRepo = $adoRepo
	gh auth login –with-token $env:GH_TOKEN
	$repoExists = $null
	$repoExists = gh repo view $githubOrg/$githubRepo
	if ($null -eq $repoExists) {
	# Use the custom extension to migrate the repository
	try {
	gh ado2gh migrate-repo –ado-org $adoOrg –ado-team-project $adoTeamProject –ado-repo $adoRepo –github-org $githubOrg –github-repo $githubRepo –target-repo-visibility 'internal'
	# get default branch and set branch protection
	Write-Output "Setting branch protection…"
	$defaultBranch = gh repo view "${githubOrg}/${githubRepo}" –json defaultBranchRef –jq '.defaultBranchRef.name'
	gh api repos/$githubOrg/$githubRepo/branches/$defaultBranch/protection –method PUT `
	-H "Accept: application/vnd.github+json" `
	-F "required_pull_request_reviews[required_approving_review_count]=1" `
	-F "required_status_checks=null" `
	-F "restrictions=null" `
	-F "enforce_admins=true" `
	# setting the repo admin
	gh api repos/$githubOrg/$githubRepo/collaborators/$repoOwner –method PUT -F permission=admin
	Write-Output "creating environments…"
	gh api repos/$githubOrg/$githubRepo/environments/production –method PUT `
	-H "Accept: application/vnd.github+json" `
	-F "deployment_branch_policy[protected_branches]=true" `
	-F "deployment_branch_policy[custom_branch_policies]=false"
	gh api repos/$githubOrg/$githubRepo/environments/dev –method PUT `
	-H "Accept: application/vnd.github+json"
	gh api repos/$githubOrg/$githubRepo/environments/qa –method PUT `
	-H "Accept: application/vnd.github+json"
	}
	catch {
	if ($LASTEXITCODE -eq 1) {
	Write-Output "Migration failed. Aborting…"
	gh ado2gh abort-migration –ado-org $adoOrg –ado-team-project $adoTeamProject –ado-repo $adoRepo –github-org $githubOrg –github-repo $githubRepo
	break
	}
	}
	if ($lockAdoRepo) {
	Write-Output "Disabling Azure DevOps repository…"
	gh ado2gh disable-ado-repo –ado-org $adoOrg –ado-team-project $adoTeamProject –ado-repo $adoRepo
	}
	} else {
	Write-Output "Repository already exists. Migration skipped."
	}

view raw migrate-devops-repo.ps1 hosted with ❤ by GitHub

	name: Migrate DevOps Repo
	on:
	workflow_dispatch:
	inputs:
	adoTeamProject:
	description: 'Azure DevOps team project'
	required: true
	adoRepo:
	description: 'Azure DevOps repository'
	required: true
	lockAdoRepo:
	description: 'Lock Azure DevOps repository'
	required: false
	type: boolean
	default: false
	jobs:
	migrate:
	name: Migrate repo, ${{ github.event.inputs.adoRepo }}
	runs-on: ubuntu-latest
	steps:
	– name: Checkout code
	uses: actions/checkout@v4
	with:
	persist-credentials: false
	ref: ${{ github.head_ref }}
	– name: Install GH CLI Extension
	run: |
	gh extension install github/gh-ado2gh
	– name: Run PowerShell script
	shell: pwsh
	run: |
	.\scripts\migrate-devops-repo.ps1 -adoTeamProject "${{ github.event.inputs.adoTeamProject }}" -adoRepo "${{ github.event.inputs.adoRepo }}" -repoOwner "${{ github.triggering_actor }}"
	env:
	GH_PAT: ${{ secrets.GH_PAT }}
	ADO_PAT: ${{ secrets.ADO_PAT }}

view raw run-repo-migration.yaml hosted with ❤ by GitHub

From Azure Pipelines to GitHub workflows

Next up in your migration is CI/CD. What do you do? In our case, we have also discussed if it’s time to ditch our deployment pipelines in favor of GitOps, using Flux or ArgoCD. All our applications run on Kubernetes (AKS), which makes this a viable option. However, it is a broader discussion, and most likely some developers want to move, and some others will not. It’s reasonable to think deployment pipelines will be a part of our setup for a long time.

Question is, should you try using the GitHub actions importer, or is a refactor about time anyway? Given the fact that the importer tool has some limitation, and you probably have wanted to do some adjustment to your existing pipelines already, I believe this project will force some refactoring anyway.

As a platform engineer, I always strive to create self-service options. Now for pipelines, I can create custom starter workflows. I really like this approach, as it provides the DevOps/Platform team a way to streamline, and scaffold the bare minimum of what’s required, and developers can adjust to their application specific needs. The example in the image above is nothing but a slightly modified standard workflow. However, with the starter workflow we can add references to our container registries, use organization secrets, use and pre-populate connection to our Azure environment. As I mentioned above with the user accounts. We want both, freedom and control!

Azure Work Items and GitHub issues

Azure work items translate to GitHub issues (almost). Work items is a part of Azure Boards, and boards are almost similar to GitHub projects. With some careful consideration and new thinking, I believe it is possible to ditch Azure Boards and work items in favor of Issues with projects. If not, you can connect Azure Boards to GitHub. As you probably have noticed, I haven’t solved this yet, but I will do my best in making it happen.

The biggest difference between the work items and issues is that work items are linked to the board, where issues are tied to one repository. After making the repo migration, you will have to create a script to pull work items from Azure DevOps and create them as issues in the correct repository on GitHub. After that, we can re-create the boards in GitHub projects. There’s a few options/scripts for doing the first task, but I believe every organization use these features differently, so customization is needed. This solution by Josh Johanning is where I will start.

I will update this post when i hit a wall or find different solutions. Until then, happy migration!