​​Repositories migreren van Azure DevOps naar GitHub Enterprise

Dit artikel behandelt het volledige proces voor het migreren van repositories van Azure DevOps Repos naar GitHub Enterprise. Daarbij kijken we naar de beschikbare tools, hoe je historie en metadata behoudt en hoe je na de migratie gebruikmaakt van de repositoryfunctionaliteiten van GitHub.

 

Breng eerst in kaart wat je migreert

Voordat je aan de migratie begint, is het belangrijk om goed in kaart te brengen wat er precies in Azure DevOps Repos staat:

• Git-repositories: de meeste teams binnen moderne Azure DevOps-omgevingen gebruiken Git. Deze repositories zijn doorgaans eenvoudig te migreren.
• TFVC-repositories: Team Foundation Version Control is het gecentraliseerde versiebeheersysteem van Microsoft. Voor een migratie vanuit TFVC is eerst een extra stap nodig om de repository naar Git om te zetten.
• Branchhistorie en tags: de volledige commithistorie, alle branches en versietags.
• Historie van pull requests: open en gesloten pull requests, opmerkingen en reviewbeslissingen.
• Repository-instellingen: branch policies, verplichte reviewers, build validation en service connections.

GitHub Enterprise ondersteunt al deze onderdelen, maar voor sommige elementen is specifieke tooling nodig om ze goed te migreren.

 

Tools voor de migratie

Microsoft en GitHub bieden tooling om het migratieproces te ondersteunen.

De GitHub Enterprise Importer (GEI) is de officiële tool voor het migreren van repositories van Azure DevOps naar GitHub Enterprise. De tool is beschikbaar als CLI-extensie, gh-gei, en ondersteunt:

• de volledige migratie van Git-historie
• de migratie van pull requests, inclusief titels, beschrijvingen, opmerkingen en status
• de migratie van repository-instellingen

Voor de meeste migraties is GEI de aanbevolen aanpak. Hiervoor heb je de juiste rechten nodig binnen zowel de bron, Azure DevOps, als de bestemming, GitHub Enterprise. De tool verwerkt de authenticatie en API-aanroepen automatisch.

Installeer de GEI-extensie met:

gh extension install github/gh-gei

Migreer één repository met:

gh gei migrate-repo \
  --github-target-org "my-org" \
  --target-repo "my-repo" \
  --ado-source-org "my-ado-org" \
  --ado-source-team-project "MyProject" \
  --ado-source-repo "MyRepo"

Voor grotere organisaties met veel repositories ondersteunt GEI bulkmigraties via een gegenereerd migratiescript. Hiermee kun je tientallen of honderden migraties achter elkaar inplannen en uitvoeren.

git-tfs voor de migratie van TFVC

Gebruik je nog repositories op basis van TFVC, dan moet je deze vóór de migratie omzetten naar Git. De tool git-tfs is hiervoor een veelgebruikte aanpak. Deze leest de TFVC-historie en zet die opnieuw op als Git-commits. Zo ontstaat een volwaardige Git-repository met volledige historie die vervolgens naar GitHub kan worden geïmporteerd.

Als alternatief biedt Azure DevOps een functie voor het importeren van repositories. Daarmee kun je een TFVC-project eerst binnen Azure DevOps omzetten naar een Git-repository en daarna GEI gebruiken.

 

Plan de migratie op schaal

Voor organisaties met tientallen of honderden repositories is een gestructureerde aanpak essentieel. Aanbevolen stappen:

1. Inventariseer je repositories: gebruik de Azure DevOps API om alle repositories, groottes, datums van laatste commits en actieve bijdragers in kaart te brengen. Zo kun je repositories indelen als actief, gearchiveerd of geschikt voor verwijdering.
2. Bepaal de structuur van je GitHub-organisatie: leg vast hoe Azure DevOps team projects worden vertaald naar GitHub-organisaties en teams. Een veelgebruikte aanpak is één GitHub-organisatie per Azure DevOps-organisatie, waarbij GitHub Teams de structuur van de team projects volgen.
3. Migreer in fases: begin met repositories met een lager risico, zoals interne tools en gearchiveerde projecten. Daarmee valideer je het proces voordat je bedrijfskritische codebases migreert.
4. Communiceer een duidelijk overstapplan: spreek voor elke repository een overstapdatum af. Zet de Azure DevOps-repository tijdens de migratie op alleen-lezen om te voorkomen dat commits verloren gaan. Na validatie kan development in GitHub worden hervat.
5. Werk integraties bij: service connections, webhooks en externe tools die naar de URL van de Azure DevOps-repository verwijzen, moeten worden aangepast. Denk vooral aan CI-pipelines, deploymenttools en IDE-configuraties.

 

GitHub-repositoryfunctionaliteiten die je direct kunt inzetten

Zodra de repositories in GitHub Enterprise staan, zijn er verschillende functionaliteiten die je direct kunt configureren om meer waarde uit de migratie te halen.

 

Branch protection rules

Met branch protection rules in GitHub kun je kwaliteits- en securitystandaarden afdwingen op belangrijke branches. Voor een gebruikelijke main branch kun je bijvoorbeeld instellen dat:

• pull request reviews verplicht zijn voordat code wordt samengevoegd, inclusief een minimumaantal reviewers
• status checks succesvol moeten zijn, zoals CI-builds en testuitvoeringen
• branches up-to-date moeten zijn voordat ze worden samengevoegd
• alleen specifieke personen rechtstreeks naar de branch mogen pushen
• ondertekende commits verplicht zijn voor betere controleerbaarheid
• force pushes en verwijderingen worden geblokkeerd

Je kunt deze regels instellen in de GitHub-interface of als code beheren met Terraform en de GitHub provider. Zo kun je ze consistent afdwingen voor alle repositories.

 

Code Owners

Met het bestand CODEOWNERS kunnen teams vastleggen wie verantwoordelijk is voor specifieke mappen of bestandstypen binnen een repository. Wanneer een pull request een bestand wijzigt waarvoor een team of persoon als eigenaar is aangewezen, vraagt GitHub automatisch een review aan bij die eigenaar.

Voorbeeld van een CODEOWNERS-bestand:

# Global owners - review all changes
*       @my-org/platform-team

# Frontend code
/src/frontend/   @my-org/frontend-team

# Infrastructure as code
/infra/          @my-org/devops-team

Hierdoor hoeft niemand handmatig te onthouden welke reviewers moeten worden toegevoegd. Tegelijkertijd weet je zeker dat de juiste personen betrokken zijn bij wijzigingen aan gevoelige delen van de codebase.

 

Repository templates

Voor nieuwe projecten kun je GitHub repository templates gebruiken om repositories vooraf te vullen met:

• een vaste mapstructuur
• standaard GitHub Actions-workflows
• een CODEOWNERS-bestand
• templates voor issues en pull requests
• een CONTRIBUTING.md- en README.md-bestand
• een standaard .gitignore- en licentiebestand

Hiermee verkort je de tijd die nodig is om een nieuw project op te zetten en zorg je ervoor dat ieder project met dezelfde basis begint.

 

Templates voor issues en pull requests

GitHub ondersteunt Markdown-templates voor issues en pull requests. Daarmee zorg je ervoor dat bijdragers de juiste informatie aanleveren bij bugs, feature requests en wijzigingen. Deze templates staan in de map .github/ van de repository en worden automatisch getoond wanneer iemand een nieuw issue of pull request opent.

 

Valideer de migratie

Vergelijk na de migratie het aantal commits en de branchhistorie tussen Azure DevOps en GitHub.

Na de migratie van iedere repository is het verstandig om het resultaat te valideren voordat je de Azure DevOps-bron uitfaseert:

• Controleer het aantal commits: vergelijk het totale aantal commits in de GitHub-repository met de Azure DevOps-bron.
• Controleer branches en tags: bevestig dat alle branches en tags aanwezig zijn.
• Controleer de historie van pull requests: bevestig dat historische pull requests correct zijn geïmporteerd.
• Test een clone: clone de GitHub-repository en controleer of de working tree overeenkomt met de verwachte situatie.
• Voer de CI-pipeline uit: start de gemigreerde of nieuw geconfigureerde GitHub Actions-workflow en controleer of de build slaagt.

 

Opruimen na de migratie

Zodra de repositories live staan in GitHub Enterprise:

• archiveer of verwijder je de Azure DevOps-repositories om verwarring te voorkomen. Zet ze eerst op alleen-lezen
• werk je documentatie, runbooks en onboardinggidsen bij waarin nog naar Azure DevOps-URL’s wordt verwezen
• werken developers hun lokale omgeving bij door hun Git remote URL aan te passen met git remote set-url origin <new-github-url>
• trek je Azure DevOps personal access tokens in die niet meer nodig zijn

 

Conclusie

Het migreren van repositories van Azure DevOps naar GitHub Enterprise is een goed ondersteund proces, met volwassen tooling en duidelijke best practices. Door de GitHub Enterprise Importer te gebruiken, de migratie in fases uit te voeren en de repositoryfunctionaliteiten van GitHub vanaf dag één in te zetten, kun je de overstap met minimale verstoring uitvoeren en developmentteams direct een betere ervaring bieden.

In het volgende artikel in deze serie kijken we naar het andere belangrijke onderdeel van de migratie: het omzetten van Azure Pipelines naar GitHub Actions-workflows.