Migrating to GitHub Enterprise Managed Users

Jenna Massardo @massardo
Staff Customer Success Architect
GitHub

What is EMU?

Enterprise Managed Users - GitHub’s centralized identity model

Think “BYOD” vs “company-issued laptops” - both work, but for different requirements.

• Usernames follow format: handle_shortcode (e.g., jsmith_acme)
• Lifecycle is fully automated: create, update, suspend, delete

Why Would You Want EMU?

When NOT to Use EMU

Stop and think before committing - EMU restrictions are real.

Your developers will need separate personal accounts for any external GitHub work. That’s two accounts, two contexts, two sets of bookmarks. Plan for the friction.

The 6-Phase Journey

A marathon, not a sprint - 12 to 26 weeks

Migration Phases at a Glance

Phases 1-4 are sequential and done once. Phases 5-6 are an iterative loop - one team at a time.

⚠️ DO NOT try to migrate everything at once.

Phase 1: Discovery & Decision

Is EMU even right for you? Define your goals first.

Document your “why”:

• Security: Time to revoke access on termination < 1 hour
• Compliance: Zero audit findings on access management
• Efficiency: 90% reduction in manual account tasks

The decision questions:

• Do we have strict compliance requirements? - EMU
• Do developers contribute to external OSS? - Standard GHEC
• Is our IdP the source of truth for all access? - EMU
• Do developers work in client repositories? - Standard GHEC
• Is preventing data exfiltration a top priority? - EMU

You need a new enterprise - existing GHEC cannot be converted to EMU. This is a migration, not an upgrade.

Phase 2: Pre-Migration Prep

Clean house before you move.

IdP Readiness - Supported combinations:

Okta + Entra ID mixed is explicitly not supported.

Inventory and cleanup checklist:

• Archive repos with no activity in 12+ months
• Close PRs inactive for 90+ days
• Delete merged/stale branches
• Audit and remove unused OAuth apps, GitHub Apps, webhooks
• Scan for committed secrets and rotate everything
• Map teams to IdP groups

Phase 3: Identity & Access Setup

Users first, then repos.

SCIM Lifecycle:

IdP assigns user → SCIM creates account → User authenticates
     → IdP attribute change → SCIM syncs → User updated
          → Unassigned from app → Account suspended

Team Sync - how it works:

• Connect each GitHub team to an IdP group
• GitHub team membership flows from the IdP group - automatically
• Manual changes in GitHub get overwritten on next sync

Common pitfalls:

• Don’t manually add users to synced teams (they’ll be removed)
• One GitHub team = one IdP group (but one IdP group can feed multiple teams)
• Plan naming conventions that work in both systems (e.g., gh-backend-team)
• Avoid rand() or generated IDs in username expressions - they will change

Phase 4: Security & Compliance

Lock it down before you move in.

Phase 5: Migration Execution

The iterative loop - one group at a time.

Tool: GitHub Enterprise Importer (GEI)

# Install
gh extension install github/gh-gei

# Dry run first - always
gh gei migrate-repo \
  --github-source-org SOURCE_ORG \
  --source-repo REPO_NAME \
  --github-target-org TARGET_ORG \
  --target-repo REPO_NAME \
  --dry-run

# Then for real
gh gei migrate-org --github-source-org SOURCE_ORG \
  --github-target-org TARGET_ORG \
  --github-target-enterprise TARGET_ENTERPRISE

After migration: Reclaim mannequins - placeholder identities that hold migrated user activity. Map them to real managed user accounts so history is attributed correctly.

Keep source active in parallel until the group is validated and productive.

Phase 6: Validation & Adoption

You’re not done when repos are moved.

Go-live checklist:

• All users can authenticate via IdP
• Team permissions are correct (spot-check cross-team access)
• CI/CD pipelines pass in the new environment
• Secrets and tokens are recreated and working
• Integrations and webhooks are responding
• Audit log streaming is active
• Users know their new username format

OSS strategy for your developers:

• Document the two-account workflow clearly
• Consider GitHub Copilot for personal account use
• Set up guidelines for what work goes where
• Some orgs use guest collaborator role for specific external contributions

Decommission checefully: Disable source repos only after a successful grace period.

Common Gotchas

Things that will bite you if you’re not careful:

• New enterprise required - You cannot convert. Budget for parallel environments.
• User communication is underrated - New usernames break muscle memory, CI configs, git configs, Slack integrations…
• Secrets don’t migrate - Every secret, token, and credential must be recreated manually.
• GitHub Apps need reinstallation - They don’t follow repos during migration.
• Okta + Entra ID mixed = broken - Pick one for SSO, one for SCIM. Actually, pick one for both.
• Don’t use rand() in SCIM expressions - Usernames will randomly regenerate.
• Big bang migrations fail - Iterate. Pilot team first. Always.
• Mannequins need manual reclaiming - Don’t skip this or contribution history is lost.

Key Takeaways

1. EMU is a different beast - Understand the restrictions before committing
2. You need a new enterprise - Plan for a migration, not an upgrade
3. IdP is the source of truth - Get it right before touching GitHub
4. Clean up before you move - Don’t pay to migrate your mess
5. Test everything - Dry runs, pilots, validation gates
6. Communicate early and often - User experience changes significantly
7. Plan for the long tail - Migration is just the beginning

Timeline reality check: 12-26 weeks. Some do it in 6-8, some take 18 months. Depends on org size and how much prep work you skip.

Get help if needed - GitHub Expert Services exists for a reason.

Questions?

Full post at dxrf.com/blog

#github #emu #enterprise #devops