Assess
A thorough assessment of your current Azure DevOps environment is essential for a successful migration. This guide helps you identify what matters most so you can plan with confidence and minimize surprises.
In this guide
| Section | Description |
|---|---|
| Azure DevOps environment analysis | Evaluate current services usage |
| Repository analysis | Analyze code repositories for migration planning |
| Integration inventory | Document integration dependencies |
| Access patterns | Map security and access controls |
| Performance considerations | Plan for migration performance |
Progress tracker
Use this checklist to help guide your assessment:
- Azure DevOps services assessed
- Repository inventory created
- Integration dependencies documented
- Access controls mapped
- Performance considerations documented
- Repository categorization completed
- Compliance requirements documented
- Migration impact analysis completed
Learning resources
Before you start, review these resources to support your assessment:
- GitHub documentation
- Microsoft Learn
Azure DevOps environment analysis
Azure DevOps services assessment
Identify which Azure DevOps services you want to retain to ensure your teams remain productive.
Azure Boards assessment
- Active projects
Decide whether to keep Azure Boards integration or move to GitHub Issues.
- Identify teams using Boards
- Document work item types and custom fields
- Map workflow customizations
- List integration points with repositories
- Catalog team dependencies on features
Azure Pipelines assessment
- Pipeline configuration
Plan your CI/CD migration approach and effort.
- Document pipeline types (classic UI based vs. YAML)
- List build and release definitions
- Map environment configurations
- Catalog variable groups, secrets and secure files
- Document service connections
- List deployment targets (consider migration alternatives if deployment groups are used)
Integration dependencies
Please refer to the training strategy in project planning for assistance in training on any additional integration dependencies.
Understanding service relationships is key to maintaining workflows:
Work item relationships
- Repository links
- Repository references (ensures traceability)
- Pull request links (preserves development history)
- Commit links (maintains audit trail)
- Build references (ensures CI/CD traceability)
Pipeline dependencies
- Build system links
- Source repositories (maps build triggers)
- Artifact feeds (ensures package continuity)
- External services (identifies integration points)
- Environment resources (maintains deployment capability)
Repository analysis
Analyzing repositories helps you plan migration batches and identify challenges early.
Initial analysis
The GitHub Enterprise Importer (GEI) tool provides a starting point. Before running the tool, ensure you have credentials configured for Azure DevOps and GitHub:
With configured credentials, use this command to generate an inventory report of your Azure DevOps environment:
gh ado2gh inventory-reportThis command scans your Azure DevOps organization and generates CSV report files:
- orgs.csv - Organization overview with counts of team projects, repositories, and pipelines
- pipelines.csv - Pipeline definitions across team projects and repositories
- repos.csv - Repository details including size, activity metrics, and pipeline usage
- team-projects.csv - Team project statistics with repository and pipeline counts
TFVC Repository Limitation: Team Foundation Version Control (TFVC) repositories cannot be directly migrated to GitHub. If your Azure DevOps environment includes TFVC repositories, you’ll need to either:
- Convert TFVC repositories to Git within Azure DevOps first using git-tfs or the Azure DevOps TFVC to Git import process
- Plan to leave TFVC repositories in Azure DevOps if conversion isn’t feasible
- Archive TFVC repository content separately if the repositories are no longer active
Identify all TFVC repositories during your assessment to plan appropriate conversion or retention strategies.
Review these reports to:
- Identify repository sizes and activity levels
- Map pipeline dependencies
- Plan migration batches based on team projects
- Identify repositories needing special handling
Repository documentation
- For each repository:
- Repository type (Git vs. TFVC) (identifies repositories that cannot be migrated)
- Size and commit history (helps estimate migration duration)
- Number of branches (identifies complexity)
- Git LFS usage (plans for large files)
- External dependencies (ensures system functionality)
- Branch protection rules (maintains code quality)
- Release tags and artifacts (preserves release history)
- Pull requests and issues (for preserving development context)
- Wiki content (for documentation preservation)
- Submodule usage (requires special handling)
- Repository hooks and webhooks (identifies automation)
Integration inventory
Understanding your integration landscape ensures business processes remain functional:
- Document current integrations:
- CI/CD pipelines - Ensures build and deployment processes continue
- External services - Maps third-party tools that need reconfiguration
- Webhooks - Identifies automation that needs updating
- Service connections - Maps authentication that needs to be recreated
- Azure Boards linkages - Maintains work item tracking functionality
Access patterns
Security and access control mapping ensures uninterrupted team productivity:
- Document current access controls:
- User roles and permissions - Maintains security posture in GitHub
- Service accounts - Ensures automation continues functioning
- Microsoft Entra ID integration settings - Plans identity management transition
- IP allow lists - Maintains network security policies
- Security policies - Ensures compliance requirements are met
Analysis and planning
Strategic categorization helps optimize the migration process:
Repository categorization
- Categorize repositories by:
- Activity level (active/inactive) - Prioritizes critical repositories
- Size (small/medium/large) - Plans migration batches efficiently
- Complexity (simple/complex) - Estimates effort and identifies risks
- Migration priority (high/medium/low) - Creates logical migration sequence
- Required features (LFS, Actions, etc.) - Ensures necessary GitHub features are enabled
- Business criticality - Identifies repositories needing additional security
Integration assessment
- For each integration:
- Document GitHub equivalent
- Plan migration approach
- Identify potential challenges
- Estimate effort required
- Document API usage and potential rate limit impacts
Access control mapping
Use this table to map your Azure DevOps permissions to their GitHub equivalents:
| Azure DevOps | GitHub |
|---|---|
| Project Collection Administrators | Organization Owner |
| Project Administrators | Repository Admin role via Organization Teams |
| Contributors | Repository Write role via Organization Teams |
| Readers | Repository Read role via Organization Teams |
| Branch Policies | Repository Rulesets |
With GitHub Enterprise Cloud, you can create custom repository roles for more granular permission control beyond the standard Read, Triage, Write, Maintain, and Admin roles.
This can be particularly useful for complex Azure DevOps permission structures that don’t map cleanly to the built-in GitHub roles.
Mapping checklist
- Map Project Collection Administrators to Organization Owners
- Create GitHub teams for Project Administrators with Admin repository role
- Create GitHub teams for Contributors with Write repository role
- Create GitHub teams for Readers with Read repository role
Compliance and security
Understanding your security and compliance requirements ensures your GitHub environment maintains or enhances your security posture:
Security requirements
- Document security requirements:
- Authentication methods - Ensures proper identity management transition
- Authorization policies - Maintains access control consistency
- IP allow lists - Preserves network security boundaries
- Secret scanning - Enhances security with GitHub’s advanced capabilities (requires GitHub Secret Protection for private repositories)
- Code scanning - Leverages GitHub’s security features (requires GitHub Code Security for private repositories)
- Security notifications - Ensures proper alerting workflows
Compliance assessment
- Review compliance requirements:
- Audit logging needs - Ensures regulatory compliance continuity
- Retention policies - Maintains data governance requirements
- Access controls - Preserves security compliance
- Security hardening - Implements GitHub security best practices
- Approval workflows - Maintains governance controls
Migration impact analysis
Understanding impact helps minimize disruption and plan proper support:
Team impact
- Assess impact on:
- Development workflows - Plans for workflow transitions and training needs
- Review processes - Ensures code quality practices are maintained
- Release procedures - Maintains reliable deployment processes
- Documentation practices - Updates process documentation appropriately
- Daily activities - Minimizes developer productivity disruption
Tool impact
- Evaluate impact on:
- Build systems - Ensures continuous integration remains functional
- Deployment processes - Maintains reliable delivery pipelines
- Testing frameworks - Preserves quality assurance processes
- Monitoring tools - Maintains system observability
- Dependencies management - Ensures proper package access
Timeline impact
- Consider impact of:
- Repository sizes - Determines migration batch planning
- Number of repositories - Influences overall timeline
- Integration complexity - Affects setup and testing duration
- Team availability - Plans around team schedules and commitments
- Freeze periods - Accommodates business requirements
Performance considerations
Understanding performance factors helps optimize the migration process:
API and rate limits
- Service boundaries
- GitHub API rate limits (plans migration pace)
- Azure DevOps API rate limits (prevents interruptions)
- Concurrent migration capacity (optimizes throughput)
- Migration tool throttling (ensures reliability)
- Network bandwidth requirements (especially for large repositories)
Migration scale planning
Execution strategy
- Repository batch sizing (optimizes efficiency)
- Migration scheduling (minimizes business impact)
- Team coordination (ensures smooth transition)
- Rollback windows (provides safety nets)
- Clone and push operation performance (especially for large repos)
Batch planning
- Group repositories with similar characteristics
- Plan for small validation batches first
- Accommodate team dependencies in batching
- Schedule high-priority repositories early
- Allow buffer time between batches for issue resolution
Next steps
After completing your environment assessment:
- Review the GitHub Well-Architected Framework for governance planning
- Proceed to Target Environment Setup to prepare your GitHub Enterprise Cloud environment