📘 Azure DevOps → GitHub Migration Playbook (Template)
- Executive Summary
- Purpose of migration (e.g., consolidation, modernization, cost optimization, open-source alignment).
- Expected outcomes (e.g., streamlined workflows, GitHub Actions adoption, improved collaboration).
- Key stakeholders and roles.
- Pre-Migration Assessment
- Inventory
- Repositories (code, artifacts, pipelines).
- Boards (work items, epics, sprints).
- Test Plans and documentation.
- Security/permissions model.
- Integrations
- CI/CD
- Telemetry
- Issue Tracking
- Project Management
- Gap Analysis
- Compare ADO features in use vs GitHub equivalents.
- Identify unsupported or custom extensions.
- Identify changes in development process
- Identify opportunities to improve development process
- Readiness Checks
- GitHub Enterprise setup (orgs, SSO, policies).
- Network/security compliance.
- Licensing and billing implications.
- Migration Strategy
- Scope Definition
- What will be migrated (repos, pipelines, boards, artifacts).
- What will be archived or retired.
- Approach Options
- Phases
- Big bang
- Self service
- Centralized migration team
- Tools & Methods
- GitHub Enterprise Importer (CLI/API).
- Manual migration for boards/test plans.
- Automation scripts for permissions and repo settings.
- Self service tool (migrations via actions)
- Detailed Migration Steps
4.1 Repository Migration
- Export/import repositories
- Reclaim mannequins
4.2 CI/CD Migration
- Map Azure Pipelines → GitHub Actions.
- Recreate workflows (build, test, deploy).
- Validate runners (hosted vs self-hosted).
4.3 Boards & Work Management
- Decide: migrate work items or start fresh in GitHub Projects.
- Align labels, milestones, and automation.
4.4 Security & Compliance
- Recreate permission model in GitHub (teams, orgs).
- Enable SSO, audit logging, and required reviews.
- Configure Dependabot, secret scanning, and code scanning.
4.5 Testing & Validation
- Dry-run migration in sandbox org.
- Validate repo integrity, pipelines, and permissions.
- Collect feedback from pilot teams.
- Cutover Plan
- Communication strategy (announce freeze windows, migration timeline).
- Final migration of repos and work items.
- Redirect integrations (CI/CD, issue trackers, external tools).
- Decommission ADO resources.
- Post-Migration Activities
- Training & enablement (GitHub Actions, Projects, Codespaces).
- Monitoring adoption and performance.
- Continuous improvement (automation, governance).
- Retrospective and lessons learned.
- Customer-Specific Customization
- Add customer-specific compliance requirements (e.g., SOC2, HIPAA).
- Tailor CI/CD workflows to their tech stack.
- Document integration points (Jira, ServiceNow, Slack, etc.).
- Include rollback/contingency plan.
- Appendices
- Tooling references (GitHub CLI, API docs).
- Migration checklists.
- Risk register.
- Glossary of terms.
Expand sections 2, 3, and 7 as needed.