🟡 MEDIUM COMPLEXITY

GitHub to Azure DevOps Migration

Streamlined migration from GitHub Issues to Azure DevOps Work Items with pipeline migration guidance and DevOps integration best practices.

Duration: 3-5 days
Data Volume: 5K-50K issues
Success Rate: 97.2%
Status: Production Ready

What Gets Migrated

GitHub to Azure DevOps migration focusing on issue tracking, labels, milestones, and DevOps workflow integration.

Issues & Pull Requests
Labels & Milestones
Comments & Reactions
User Assignments
Repository Metadata
Issue References

DevOps Integration Focus: This migration is ideal for teams consolidating from GitHub Issues to Azure DevOps Work Items. Git repositories can remain on GitHub (Azure DevOps integrates natively) or be migrated separately. Pipeline migration covered in best practices section.

Table of Contents

1. Prerequisites

GitHub Requirements

Azure DevOps Requirements

Technical Requirements

2. Connector Setup

Step 1: Configure GitHub Connector

Generating GitHub Personal Access Token:

  1. Navigate to GitHub.com → Settings → Developer settings → Personal access tokens → Tokens (classic)
  2. Click Generate new token (classic)
  3. Configure scopes:
    • repo (full control of private repositories)
    • read:org (read organization membership)
    • read:user (read user profile data)
  4. Set expiration: 90+ days
  5. Copy token immediately

GitHub Connector Configuration:

{ "connectorType": "GitHub", "baseUrl": "https://api.github.com", "authentication": { "authMethod": "PersonalAccessToken", "token": "ghp_YOUR_PERSONAL_ACCESS_TOKEN" }, "githubConfiguration": { "owner": "your-organization-or-username", "repositories": ["repo1", "repo2", "repo3"], "includeAllRepos": false }, "dataOptions": { "includeIssues": true, "includePullRequests": true, "includeComments": true, "includeReactions": true, "includeClosedIssues": true, "closedIssueCutoffDays": 365 }, "rateLimiting": { "maxRequestsPerHour": 4500, "useGraphQL": true } }

Rate Limit Strategy: GitHub allows 5,000 requests/hour for authenticated users. OpsMigrator uses GraphQL API (single request for issue + comments + labels) to minimize API calls. For 10K issues, expect 500-800 API calls (well within limits). Migration typically completes in 2-4 hours for data extraction.

Step 2: Configure Azure DevOps Connector

Generating Azure DevOps PAT:

  1. Navigate to https://dev.azure.com/{organization}
  2. Click profile icon → Personal access tokens
  3. Click + New Token
  4. Configure scopes:
    • Work Items: Read, Write, & Manage
    • Code: Read & Write (if migrating repositories)
    • Project and Team: Read
    • Identity: Read
  5. Set expiration: 90+ days
  6. Copy PAT token immediately

Azure DevOps Connector Configuration:

{ "connectorType": "AzureDevOps", "baseUrl": "https://dev.azure.com/{organization}", "authentication": { "authMethod": "PAT", "personalAccessToken": "YOUR_PAT_TOKEN" }, "adoConfiguration": { "organization": "your-org", "project": "YourProject", "apiVersion": "7.1", "areaPath": "YourProject\\GitHub Migration", "iterationPath": "YourProject\\Current", "processTemplate": "Agile" }, "workItemMapping": { "issueType": "User Story", "pullRequestType": "Task", "defaultState": "New" } }

Step 3: Validate Connections

# Validate both connectors opsmigrator connector validate --source github-connector.json opsmigrator connector validate --target ado-connector.json # Expected output: ✓ GitHub connection successful - Organization: your-org - Repositories: 3 (repo1, repo2, repo3) - Open Issues: 847 - Closed Issues (last 365 days): 1,293 - Rate Limit: 4,987/5,000 remaining ✓ Azure DevOps connection successful - Organization: your-org, Project: YourProject - Process Template: Agile - Area Path: YourProject\GitHub Migration - User mapping: 94% matched (6% require provisioning)

3. Issue to Work Item Conversion

Issue Type Mapping Strategy

GitHub Type Azure DevOps Work Item Rationale
Issue (default) User Story Most GitHub issues represent features/user stories
Issue with "bug" label Bug Label-based classification
Issue with "enhancement" label User Story Feature enhancement maps to user story
Issue with "task" label Task Direct task mapping
Pull Request Task (linked to original issue) PR becomes implementation task

Field Mapping

GitHub Field Azure DevOps Field Transformation Notes
Title Title Direct mapping
Body (Description) Description Markdown preserved; GitHub mentions converted to ADO format
State (open/closed) State (New/Active/Closed) Open→New/Active (based on assignee), Closed→Closed
Labels Tags All labels become tags; special labels (bug, enhancement) also determine work item type
Assignee Assigned To User identity mapping: GitHub username → Azure AD email
Milestone Iteration Path GitHub milestones map to ADO iterations
Comments Discussion All comments preserved with original author and timestamp
Reactions (👍, ❤️) Custom Field (optional) Reaction counts preserved in custom field or comment
Issue References (#123) Related Links GitHub issue references become ADO work item links

Label-Based Classification: OpsMigrator scans all labels across repositories to detect common patterns (bug, enhancement, task, documentation, etc.). You can customize classification rules to match your team's labeling conventions. Default rules achieve 85-90% accurate work item type assignment.

4. Migration Process (5 Phases)

1

Discovery & Analysis

Duration: 2-4 hours

  • Connect to GitHub and scan repositories
  • AI analysis: 10-20 minutes for 10K issues
  • Label pattern detection (bug, enhancement, task)
  • User identity mapping (GitHub → Azure AD)
  • Output: Migration plan report
2

Configuration

Duration: 1-2 days

  • Review work item type mappings
  • Configure milestone → iteration mapping
  • Resolve unmapped users
  • Define area paths for repositories
  • Workshops: 1 session (2 hours)
3

Pilot Migration

Duration: 1 day

  • Migrate 1 repository (500-1K issues)
  • Validate work item types and links
  • User acceptance testing
  • Execution: 1-2 hours
  • Iterations: 1 cycle
4

Production Migration

Duration: 1-2 days

  • Migrate all repositories
  • Throughput: 5K-10K issues/day
  • Real-time monitoring and error handling
  • Execution: 4-8 hours
  • GitHub Status: Remains operational
5

Validation & Cutover

Duration: 1 day

  • Comprehensive validation report
  • User training on Azure Boards
  • Parallel operation (GitHub + ADO)
  • GitHub Issues disable (optional)
  • Support: 1 week hypercare

Success Story

SaaS Startup - 4-Day Migration

  • Scale: 12,487 issues across 8 repositories, 37 users, 94 labels
  • Challenge: 5 years of GitHub Issues history, 4,200 closed issues, complex label taxonomy
  • Result: 99.1% data accuracy, 100% link preservation, all comments migrated
  • Timeline: 4 days total (2 hours pilot, 6 hours production migration)
  • Outcome: Seamless DevOps consolidation, GitHub repos remain (Azure DevOps integration), 94% user adoption within 1 week

5. Pipeline Migration Guidance

GitHub Actions to Azure Pipelines

Pipeline migration is separate from issue migration but often part of consolidation strategy:

GitHub Actions Concept Azure Pipelines Equivalent Migration Approach
Workflow YAML (.github/workflows/) Pipeline YAML (azure-pipelines.yml) Manual conversion (syntax differs); OpsMigrator provides conversion assistant
Jobs Jobs Direct mapping with syntax adjustments
Steps Steps Direct mapping; "uses" actions must be converted to tasks
Marketplace Actions (uses: actions/...) Azure DevOps Tasks (task: ...) Find equivalent task or recreate as script step
Secrets Pipeline Variables (secret) Manual recreation in Azure DevOps Library
Environments Environments Recreate in Azure DevOps with approvals

Pipeline Migration Complexity

Not Automated: GitHub Actions → Azure Pipelines conversion requires manual effort (YAML syntax incompatible). OpsMigrator provides conversion assistant (50-70% automated) but human review required. Budget 2-4 hours per pipeline for conversion + testing. Alternatively, keep GitHub repos and use Azure Pipelines with GitHub integration (no YAML conversion needed).

Repository Migration Options

Hybrid Approach: 80% of teams keep GitHub repositories and migrate only issue tracking to Azure DevOps. This provides best of both worlds: GitHub's code collaboration + Azure DevOps' comprehensive work item tracking and reporting. Azure DevOps Boards integrates seamlessly with GitHub commits and PRs.

6. Red Flags & Mitigation

Complex Label Taxonomy (94 labels)

MEDIUM

Detection: 94 labels detected across repositories; many are repository-specific

Impact: Azure DevOps work items become cluttered with 94 tags; users overwhelmed.

Mitigation:

  • OpsMigrator provides label usage analysis (frequency, last used date)
  • Consolidate labels: "bug" + "Bug" + "🐛 bug" → single "bug" tag
  • Archive labels used <5 times (preserve in custom field for history)
  • Typical reduction: 94 labels → 25-35 meaningful tags

User Identity Mismatch (12 users)

MEDIUM

Detection: 12 GitHub users have no matching Azure AD account

Impact: Work items cannot be assigned; validation fails.

Mitigation:

  • Export user mapping report from OpsMigrator
  • Provision Azure AD accounts for active users (coordinate with IT)
  • Map external contributors to generic "External Contributor" account
  • Preserve original GitHub username in custom field

GitHub Mentions (@username)

LOW

Detection: Issue descriptions/comments contain GitHub mentions (@username)

Impact: Azure DevOps mentions use different syntax; references break.

Mitigation:

  • OpsMigrator auto-converts: @githubuser → @azuread-email
  • Unmatched users: @githubuser → @githubuser (text preserved, mention disabled)
  • 90-95% mention conversion success rate

Pull Request History

LOW

Detection: 2,400 closed pull requests in GitHub history

Impact: PRs don't have direct equivalent in Azure DevOps Boards (PRs are in Azure Repos).

Mitigation:

  • OpsMigrator creates Task work items for PRs (linked to original issue if referenced)
  • PR metadata preserved: Title, Description, Author, Merged Date, Branch names
  • Link to original GitHub PR in work item for full history
  • If repos migrated to Azure Repos: GitHub PR history inaccessible (archive externally)

7. Best Practices

Before Migration

During Migration

After Migration

8. Frequently Asked Questions

Do I have to migrate GitHub repositories to Azure Repos?

No. Azure DevOps integrates natively with GitHub repositories. 80% of teams keep repos on GitHub and migrate only issue tracking to Azure DevOps Boards. Azure Pipelines can build from GitHub repos, and work items can link to GitHub commits/PRs. Only migrate repos if you want full consolidation into Azure DevOps ecosystem.

What happens to GitHub Actions workflows?

GitHub Actions workflows remain functional on GitHub (if repos stay on GitHub). If you want to migrate pipelines to Azure Pipelines, manual YAML conversion required (syntax incompatible). OpsMigrator provides conversion assistant (50-70% automated). Budget 2-4 hours per pipeline. Alternatively, use Azure Pipelines with GitHub integration (no YAML conversion needed).

Are GitHub Issue numbers preserved in Azure DevOps?

No. Azure DevOps assigns sequential work item IDs starting from 1 (or next available). OpsMigrator preserves GitHub issue number in custom field "GitHub Issue #" for reference. Issue references in comments (#123) are converted to Azure DevOps links (work item ID). For 10K GitHub issues starting at #1 → Azure DevOps work items starting at #5001 (if project has 5K existing items).

How long does GitHub need to be offline?

GitHub does NOT need to be offline. Migration is read-only operation (no data locked). Teams continue working in GitHub during migration. After migration complete, run parallel operation (GitHub + Azure DevOps) for 1-2 weeks, then cutover. To prevent new issues during migration window, temporarily disable GitHub Issues in repo settings (optional).

Can I migrate only open issues?

Yes. OpsMigrator supports selective migration by state, label, milestone, or date range. Common strategy: Migrate open issues + closed issues from last 6-12 months (operational focus). Reduces scope by 60-80% for mature projects. Keep GitHub accessible for historical reference.

What's the typical cost for GitHub → ADO migration?

Costs include: OpsMigrator license, consultant fees, Azure DevOps licensing (if new), user training. Pipeline conversion (if needed): add $5K-$20K depending on pipeline complexity.

Ready to Consolidate Your DevOps Tools?

Schedule a demo to see how OpsMigrator simplifies GitHub to Azure DevOps migration.

Schedule Demo Contact Sales
Back to Documentation Hub