GitHub

🔴 Issue: Fine-Grained Tokens Not Supported

Problem: Many migration tools like gh-ado2gh do NOT support fine-grained tokens.

Solution: Always use Classic PAT for migrations and GitHub CLI extensions.

How to Create Classic PAT

1. Go to: GitHub Settings → Developer settings → Personal access tokens → Tokens (classic)

2. Click "Generate new token (classic)"

3. Select required scopes:

• ✅ repo - Full control of repositories
• ✅ workflow - Update workflows
• ✅ admin:org - Full control of organizations
• ✅ delete_repo - Delete repositories (if needed)

🔴 Issue: Token Expired

Problem: PATs expire after the configured period (30, 60, 90 days, etc.)

Solution: Check token expiration and regenerate if needed:

• Go to: Settings → Developer settings → Personal access tokens

• Check expiration date

• Click "Regenerate token" to create new one

• Update environment variables: $env:GH_PAT = "new_token"

🔴 Issue: Insufficient Token Permissions

Problem: Token doesn't have required scopes for operations

Solution: Edit token and add missing scopes:

• For migrations: repo, admin:org, workflow

• For API access: read:user, read:org

• For secrets: admin:repo_hook

Verify Token Works

Test your token with GitHub CLI:

gh auth login
gh auth status

🔴 Issue: Tool Says "Organization Not Found"

Problem: You're trying to use a personal account instead of an organization.

Examples of personal accounts:

• ❌ https://github.com/username
• ❌ Using your personal profile as migration target

Organizations look like:

• ✅ https://github.com/mycompany-org
• ✅ Has "Organizations" label in GitHub

How to Check if You Have an Organization

Method 1: Via GitHub UI

1. Click your profile picture (top-right)

2. Look for "Your organizations" section

3. If empty or missing → You need to create one

4. If organizations listed → You already have one! ✅

Method 2: Check URL

• Personal account: Shows "Overview, Repositories, Projects, Packages" tabs

• Organization: Shows "Repositories, People, Teams, Projects" tabs

How to Create GitHub Organization

Step 1: Go to https://github.com/organizations/plan

Step 2: Choose a plan (Free is fine for most users)

Step 3: Set organization name (e.g., mycompany-dev)

Step 4: Enter contact email

Step 5: Select ownership type (Personal or Business)

Step 6: Add members (optional, can do later)

Step 7: Verify creation at https://github.com/YOUR-ORG-NAME

Organization Settings for Migrations

After creating organization, configure:

• ✅ Go to: Settings → Member privileges
• ✅ Base permissions: Read (more secure)
• ✅ Allow private repo creation: Enabled
• ✅ Third-party access: No restrictions (for gh-ado2gh)

🔴 Issue: Organization vs Personal Account Differences

Personal Account:

• ❌ Cannot use migration tools
• ❌ No team management
• ❌ Limited collaboration features
• ❌ No environment approvals

Organization:

• ✅ Full migration support
• ✅ Team management
• ✅ Advanced security features
• ✅ Environment protection rules

🔴 Issue: "Permission Denied" or "403 Forbidden"

Problem: You don't have sufficient permissions in the organization.

Solution: Verify you are an Organization Owner, not just a Member.

How to Check Your Role

Step 1: Go to https://github.com/orgs/YOUR-ORG-NAME/people

Step 2: Find your username in the list

Step 3: Check the Role column:

• ✅ Owner - You can proceed with migrations ✓
• ❌ Member - Ask an Owner to promote you

How to Become Organization Owner

Option 1: Ask Current Owner

1. Contact an existing Owner

2. They go to: https://github.com/orgs/YOUR-ORG/people

3. Find your username → Click "..."

4. Select "Change role" → "Owner"

Option 2: Create Your Own Organization

If you created the organization, you're automatically the Owner.

🔴 Issue: Migrator Role Not Assigned

Problem: Migration fails with "insufficient permissions" even though you're an Owner.

Solution: Assign the Migrator role to your account:

gh ado2gh grant-migrator-role `
  --github-org "your-org-name" `
  --actor "your-username" `
  --actor-type USER

Requirements:

• ✅ Must be Organization Owner
• ✅ Must use Classic PAT (not fine-grained)
• ✅ Token must have admin:org scope

🔴 Issue: Repository Permission Denied

Problem: Can't push or create repositories in organization.

Solution: Check organization member privileges:

1. Go to: Settings → Member privileges

2. Check "Repository creation" settings

3. Enable: "Allow members to create private repositories"

4. Or ensure you have Owner role (bypasses restrictions)

Permission Levels Explained

🔴 Issue: "Repository Already Exists"

Problem: Target repository name is already taken in GitHub organization.

Solution 1: Delete existing repository (if safe to do so)

gh repo delete your-org/your-repo --confirm

Solution 2: Rename target repository in migration script

--github-repo "your-repo-v2"

🔴 Issue: "File Size Exceeds 100 MB Limit"

Problem: GitHub has a 100 MB file size limit, but your repo has larger files.

Solution: Use Git LFS (Large File Storage)

git lfs install
git lfs migrate import --include="*.zip,*.dll,*.exe,*.bin"
git push origin --all --force

Alternative: Remove large files from history:

git filter-branch --tree-filter 'rm -rf path/to/large/file' HEAD

🔴 Issue: "Migration Timeout" or "Network Error"

Problem: Large repositories or slow network causing timeouts.

Solution 1: Retry the migration (may succeed on second attempt)

Solution 2: Manual git push for very large repos:

git clone https://dev.azure.com/org/project/_git/repo
cd repo
git remote add github https://github.com/org/repo.git
git push github --all
git push github --tags

Solution 3: Migrate in smaller batches during off-peak hours

🔴 Issue: "User Mapping Failed"

Problem: Can't map Azure DevOps users to GitHub accounts.

Cause: Users don't have matching email addresses or no GitHub account

Solution:

• • Ensure users have GitHub accounts
• • Match email addresses in both systems
• • Invite users to GitHub organization first
• • Accept manual attribution for unmapped users

🔴 Issue: "Authentication Failed" During Migration

Problem: PAT authentication fails mid-migration.

Solution: Re-verify environment variables:

# Verify PATs are set
Write-Host "GH_PAT: $($env:GH_PAT.Substring(0,10))..."
Write-Host "ADO_PAT: $($env:ADO_PAT.Substring(0,10))..."

# Re-authenticate GitHub CLI
gh auth login
gh auth status

🔴 Issue: "Rate Limit Exceeded"

Problem: GitHub API rate limits hit during bulk migrations.

Solution:

• • Wait for rate limit to reset (check: gh api rate_limit)
• • Migrate in smaller batches
• • Add delays between migrations
• • Use authenticated requests (increases limit from 60 to 5000/hour)

How to Monitor Migration Progress

Check migration status and logs:

# Check migration status
gh ado2gh migration-status --github-org "your-org"

# View migration logs
Get-Content .\migration-*.log -Tail 20

# Check for errors
Get-Content .\migration-*.log | Select-String "error"

Step 1: Enable Dependabot

Go to your repository → Settings → Security & analysis

Step 2: Enable Features

Enable Dependabot alerts, Dependabot security updates, and Dependabot version updates

Step 3: Configure (Optional)

Create .github/dependabot.yml to customize update schedules and package ecosystems

Step 4: Review PRs

Dependabot will automatically create pull requests when vulnerabilities are found or updates are available

Step 1: Enable Code Scanning

Go to Security tab → Code scanning alerts → Set up code scanning

Step 2: Choose Setup Method

Select Default (easiest) or Advanced (custom workflow)

Step 3: Configure Languages

CodeQL supports: JavaScript/TypeScript, Python, Java, C/C++, C#, Go, Ruby, and more

Step 4: Review Alerts

CodeQL will scan on every push and pull request, showing vulnerabilities in the Security tab

Step 1: Enable Secret Scanning

Go to Settings → Security & analysis → Enable Secret scanning

Step 3: Reporting Instructions

Provide clear instructions on how to report vulnerabilities (email, private advisory, etc.)

Step 4: Response Timeline

Set expectations for response time and disclosure timeline