Azure DevOps to GitHub Migration Guide

Guide Overview

What the guide includes

This guide is intended for teams moving source control and delivery workflows from Azure DevOps to GitHub. It combines the original website content into one HTML page so it can be shared or opened directly without a site generator.

Covered In This Guide

Repository migration with complete history.
Branch, tag, and Git configuration preservation.
Pipeline conversion to GitHub Actions.
Authentication, secrets, and access setup.
Enterprise discovery and migration planning.
Terraform-backed infrastructure preparation.

Not Migrated Automatically

Azure DevOps Boards and work items.
Pull requests and approval history.
Wiki content.
Azure Pipelines definitions.
Repository permissions and policies.
Build artifacts and releases.

Repository Size	Typical Duration	Suggested Path
Small, under 100 MB	1 to 2 hours	Web importer or CLI
Medium, 100 MB to 1 GB	2 to 8 hours	Web importer or CLI
Large, above 1 GB	1 to 3 days	CLI with validation
Enterprise, multiple repositories	1 to 4 weeks	CLI plus automation and phased rollout

Unified platform Better collaboration Actions ecosystem Security tooling Automation-ready

Architecture

Migration architecture at a glance

The end-to-end architecture is organized into staged layers so teams can move from discovery to validation with clear traceability.

1. Discovery and prerequisites

Validate Azure DevOps organization and repository access.
Prepare GitHub destination organizations, repositories, and credentials.
Confirm migration scope, sequencing, and success criteria.

2. Migration execution

Run repository migration by web importer or CLI.
Convert or refactor pipelines into GitHub Actions.
Use repeatable scripts to reduce manual variance.

3. Infrastructure and state

Use Terraform-managed Azure resources where infrastructure is part of the move.
Maintain consistent backend and state storage.
Capture outputs and variables needed for deployment workflows.

4. Validation and rollout

Verify repositories, branches, and pipeline behavior.
Run smoke tests and policy validation.
Complete phased rollout and handoff.

Prerequisites

Prepare access, accounts, and clone credentials

Before migrating anything, verify the target GitHub permissions, Azure DevOps repository access, repository clone URLs, and the Personal Access Token required for authentication.

GitHub account and organization setup

Create or confirm a GitHub account with the correct permission scope for the destination repositories.

Account Type	Best Fit	Notes
Free	Individuals and learning projects	Private repositories supported, limited Actions minutes.
Pro	Professional developers	Extra minutes, protected branches, insights.
Team	Development teams	Team controls and collaboration features.
Enterprise	Large organizations	Audit, security, compliance, self-hosted runners.

Create the account at github.com and verify email.
Enable two-factor authentication.
Create or join the target organization.
Verify you can create repositories and configure secrets.

Azure DevOps access verification

You need at least Contributor-level repository access to clone and migrate repositories.

Permission Level	Can Migrate	Notes
Reader	No	Cannot perform the required clone operations.
Contributor	Yes	Minimum viable permission set.
Project Administrator	Yes	Full access inside the project.
Organization Administrator	Yes	Global access and policy control.

Check organization users and project permissions.
Open Repos and confirm the target repository is visible.
Verify Clone, Read, and Pull permissions.
Request access from project or organization administrators if needed.

Finding and validating the clone URL

Use the Azure DevOps HTTPS clone URL. The standard format is shown below.

https://dev.azure.com/{organization}/{project}/_git/{repository}

Navigate to Repos and open the target repository.
Select Clone, choose HTTPS, and copy the URL.
Open the URL in a browser to verify it resolves to the right repository.
Remove any query parameters if you copied it from the address bar.

URL considerations

Use HTTPS for GitHub importer. Repository names with spaces or special characters are automatically URL-encoded when copied from Azure DevOps.

Creating an Azure DevOps Personal Access Token

Create a scoped PAT with the minimum permissions required for repository reads.

Open Azure DevOps personal access tokens from your profile menu.
Create a new token with a descriptive name such as GitHub Migration Token.
Select the correct organization and the shortest viable expiration window.
Grant Code with Read permission only.
Copy the token immediately and store it in a secure password manager.

Duration	Recommended For
7 days	Quick, one-off migrations
30 days	Standard project migrations
90 days	Large enterprise programs

Security rules

Do not commit PATs to source control, store them in plain text, or share them in chat. Revoke the token as soon as the migration is complete.

Migration Methods

Choose the migration path that matches repository size and team maturity

The original site documented three practical execution options: GitHub's web importer, a full CLI workflow, and an automated PowerShell-driven path.

Web interface migration

Best for small to medium repositories, new Git users, and quick one-time imports under GitHub importer limits.

Open the importer at github.com/new/import.
Paste the Azure DevOps HTTPS clone URL.
Authenticate with Azure DevOps username and PAT.
Create the destination repository and begin import.
Verify files, commits, branches, and tags after completion.

Limit	Value
Maximum repository size	5 GB
Maximum file size	100 MB
Maximum push size	2 GB

CLI migration

Best for large repositories, Git LFS, scripted migrations, or when full control over the mirror process is required.

gh auth login
gh repo create my-migrated-repo --private --description "Migrated from Azure DevOps"
git clone --mirror https://username:PAT@dev.azure.com/org/project/_git/repo
cd repo.git
git remote add github https://github.com/username/my-migrated-repo.git
git push --mirror github

Authenticate with GitHub CLI first.
Create the destination GitHub repository.
Mirror-clone the Azure DevOps repository.
Add GitHub as a second remote.
Push all refs, branches, and tags with mirror mode.

When to use PowerShell automation

Use the scripted approach when migrating multiple repositories in Windows-heavy environments or when you want an opinionated workflow with prerequisite checks and guided prompts.

Interactive input collection for GitHub and Azure DevOps details.
Built-in checks for Git and GitHub CLI.
Automated repository creation, mirror clone, remote add, and push.
Cleanup and optional browser launch at the end.

Common troubleshooting across migration methods

Repository not found: verify the clone URL directly from Azure DevOps.
Authentication failed: confirm username format and PAT scope.
Import timed out or failed: use the CLI path for large repositories.
Missing branches or commits: re-run using mirror clone and mirror push.

12-Step Process

Recommended end-to-end migration workflow

The migration process moves from discovery through preparation, cutover, validation, and production rollout. Follow the steps sequentially and validate each one before proceeding.

Discovery -> Preparation -> Repo Migration -> Lockdown -> Secrets -> Runners -> Pipeline Creation -> Authentication -> Testing -> Fixing -> Push Changes -> Production Validation

Step 1

Initial client discovery

Inventory repositories, pipelines, dependencies, and complexity.

Step 2

Environment preparation

Create GitHub org structures, permissions, and migration tooling.

Step 3

Repository migration

Move repositories with full history and validate the result.

Step 4

Azure DevOps lockdown

Make the source repository read-only and notify developers.

Step 5

Secrets and variables

Re-create repository secrets and environment variables in GitHub.

Step 6

Runner configuration

Set up GitHub-hosted or self-hosted runners.

Step 7

Pipeline creation

Convert Azure Pipeline definitions to GitHub Actions workflows.

Step 8

Authentication setup

Configure cloud credentials, OIDC, or service principals.

Step 9

Migration testing

Trigger workflows and validate outputs, deployments, and logs.

Step 10

Issue fixing

Iteratively debug syntax, dependencies, and environment differences.

Step 11

Push final changes

Commit workflow configuration and update supporting docs.

Step 12

Production validation

Run the production pipeline and confirm everything works.

Repository Type	Total Timeline	Typical Notes
Simple	1 to 2 days	No pipelines or minimal integration work.
Medium	3 to 5 days	One or two pipelines plus validation.
Complex	1 to 2 weeks	Multiple pipelines and higher dependency count.
Enterprise	6 to 8 weeks	Many repositories, teams, and phased rollout.

Decision points and rollback guidance

Method selection

Use web import for repositories under 5 GB and simple one-off moves.
Use CLI for large repositories, batch migrations, or Git LFS.
Use PowerShell automation in Windows enterprise workflows.

Runner selection

Use GitHub-hosted runners for standard public-network builds.
Use self-hosted runners for private network access or special toolchains.

Immediate rollback: re-enable Azure DevOps and notify the team.
Partial rollback: keep GitHub repositories but temporarily continue using Azure Pipelines.
Prevention: test in non-production, document rollback, and keep ADO access during transition.

Pipeline Conversion

Map Azure Pipelines concepts to GitHub Actions

Azure DevOps and GitHub Actions both use YAML, but the pipeline model, naming, and integration mechanisms differ. Treat conversion as a structured refactoring rather than a direct text rewrite.

Azure DevOps	GitHub Actions	Notes
trigger	on	Defines when a workflow executes.
pool	runs-on	Defines the runner or agent image.
stages	jobs	High-level pipeline grouping becomes jobs.
task	uses or run	Vendor tasks map to actions or shell commands.
variables	env or secrets	Choose based on sensitivity and scope.
service connections	Secrets or OIDC	Prefer OIDC where supported.

Example translation

Azure DevOps
trigger:
- main

pool:
  vmImage: 'ubuntu-latest'

steps:
- task: NodeTool@0
  inputs:
    versionSpec: '16.x'
- script: npm install
- script: npm test

GitHub Actions equivalent

name: CI Pipeline

on:
  push:
    branches: [ main ]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '16'
      - run: npm install
      - run: npm test

Common task mappings

Azure DevOps Task	GitHub Actions Equivalent
checkout: self	actions/checkout@v4
NodeTool@0	actions/setup-node@v4
UseDotNet@2	actions/setup-dotnet@v4
UsePythonVersion@0	actions/setup-python@v5
Docker@2 buildAndPush	docker/build-push-action@v5
AzureCLI@2	azure/login plus shell commands
PublishBuildArtifacts@1	actions/upload-artifact@v4
DownloadBuildArtifacts@0	actions/download-artifact@v4

Conversion guidance

Analyze triggers, agent pools, custom tasks, templates, variables, secrets, and service connections first. The hard part is usually external dependency mapping and authentication, not YAML syntax.

Discovery and Analysis

Front-load the inventory work before the first migration

The discovery phase reduces migration risk by exposing repository size, pipeline complexity, external integrations, and compliance requirements before execution begins.

Repository inventory

Repository name and business owner.
Repository size, large files, and Git LFS usage.
Branch count, commit count, and contributor activity.
Last activity date and migration priority.

git count-objects -vH
git branch -r
git rev-list --count --all

Pipeline analysis

Count pipelines per repository.
Capture triggers, stages, tasks, templates, and dependencies.
List service connections, secrets, and deployment environments.
Identify classic UI pipelines that need manual YAML conversion.

Integration points

Cloud services across Azure, AWS, or GCP.
Artifact registries, package feeds, and container registries.
Monitoring systems such as Application Insights or Datadog.
Notification channels like Teams or Slack.

Security and compliance

Compliance standards and audit expectations.
Secret management requirements.
Access models and environment controls.
Data residency or regulatory constraints.

Complexity	Criteria	Migration Effort
Simple	Under 100 MB, under 10 branches, no pipelines	1 to 2 hours
Medium	100 MB to 1 GB, 10 to 50 branches, 1 to 3 pipelines	4 to 8 hours
Complex	Above 1 GB, many branches, multiple pipelines	1 to 3 days
Critical	Production workloads and high dependency density	3 to 7 days

Risk assessment examples

Risk	Severity	Mitigation
Repository larger than web importer supports	High	Use CLI mirror migration.
Complex pipeline dependencies	Medium	Allocate extra conversion and testing time.
Many active developers	Medium	Schedule migration windows and freeze periods.
Production deployment pathways	High	Stage first and validate with rollback procedures.

Client Discovery

Use a structured questionnaire before planning the cutover

The questionnaire in the original site was designed to collect enough information to define scope, estimate effort, identify risks, and align on success criteria.

Business goals and drivers

Why is the team migrating to GitHub?
What is the required timeline and urgency?
Are there blackout windows or downtime constraints?
How will migration success be measured?

Repository inventory

Total repositories, archived repositories, and test repositories.
Monorepos, large binaries, and branching strategy.
Priority, last activity, and representative complexity samples.

CI/CD and automation

What CI/CD systems are in use today?
How many build, test, deployment, and scheduled pipelines exist?
Are pipelines YAML-based, UI-defined, or mixed?
Are custom tasks, templates, or extensions involved?

Integrations and environments

Which cloud platforms, subscriptions, and accounts are connected?
Where are artifacts stored?
Which monitoring, chat, and quality tools are integrated?
What type of agents or runners are needed?

Questionnaire outcome

The goal is not just information gathering. The output should become a migration plan with repository priorities, identified blockers, target timelines, and success metrics that stakeholders agree to before execution.

Terraform

Infrastructure as code support for repeatable environments

The original Terraform documentation described a supporting Azure infrastructure layout that can be provisioned consistently and tracked in source control.

Resources covered

Azure resource group.
Linux App Service plan.
Linux web app.
Storage account and private container.
Azure Container Registry.
Optional SQL resources noted as currently disabled.

Configuration files

provider.tf for provider and client config.
variables.tf for inputs such as location and tags.
backendstg.tf for remote state storage.
output.tf for resource names and endpoints.

terraform init
terraform validate
terraform plan
terraform apply

Prerequisite	Reason
Terraform installed	Required to initialize, validate, plan, and apply IaC.
Azure CLI installed	Used for Azure authentication and subscription selection.
Azure login completed	Needed before provisioning or planning against a subscription.

PowerShell Automation

Interactive automation for repeatable repository migration

The PowerShell scripts documented in the site automate the CLI path with user prompts, validation, and cleanup. They are intended for Windows users who want a repeatable guided migration flow.

Interactive migration script workflow

Check whether Git is installed.
Check whether GitHub CLI is installed and authenticated.
Prompt for GitHub owner, repository name, Azure DevOps username, PAT, organization, project, and repository name.
Create the destination GitHub repository.
Mirror-clone the Azure DevOps repository.
Add GitHub as a remote and push with mirror mode.
Remove temporary clone data and optionally open the result in a browser.

# Typical steps performed by the script
gh repo create repo-name --private --description "Migrated from Azure DevOps"
git clone --mirror https://ado-user:PAT@dev.azure.com/org/project/_git/repo
cd repo.git
git remote add github https://github.com/github-user/repo-name.git
git push --mirror github

Operational caution

Because the script collects credentials and repository details interactively, confirm that your terminal history, logging, and execution environment are appropriate for handling sensitive values.