Migration to GitHub EMU: Lessons Learned

Pulkit Aggarwal — Sun, 18 Oct 2026 03:58:46 +0000

Migrating 1,400+ repos to GitHub EMU: lessons learned

A couple of months back, I led the migration of multiple GitHub organisations with about 1,400+ repositories from github.com to GitHub Enterprise Managed Users (EMU). This post collects what the official docs and GitHub's own migration tooling leave out.

TL;DR

Decide your org name strategy on day one. If your org name is referenced throughout your code, the two-rename swap keeps every github.com/your-org/... URL and Go import path intact (explained later in the post). This whole guide is written considering one is following the rename to the same org name approach but there are parts of this which is useful to everyone.
Don't depend on gh-gei at scale. Custom mirror-and-push tooling, validated with a separate framework, replaced it. This tooling is not great, bad logs and no understanding of why a repository fails migration. Large repositories just cannot depend on this.
Secrets, Apps, webhooks, variables, runners and branch protections don't come with you. Inventory them before the cutover, not during it.
The org rename and the IdP update must happen together. Any gap, and every user loses SSO access.
Rollback is clean only until you rename the source org. After that, it's forward-fix.
This migration is going to be really hard as there's a lot of moving parts.

Why EMU

With a regular GitHub organisation, people sign in with personal accounts that they own and carry between employers, projects and their own side work. SSO can sit in front of the org, but the identity itself isn't yours. EMU flips that. Every account is created and managed through your identity provider, and it only exists inside your enterprise. When someone is de-provisioned in the IdP, their GitHub access goes with it.

Policy is set once at the enterprise level rather than org by org. And because managed users can't contribute outside the enterprise, there is a clear boundary around where your code lives and who can touch it.

The two decisions that shape everything in this migration

1. Keep your org name: the two-rename swap

Go modules embed github.com/{org}/{repo} in go.mod and in every import of an internal package. If the org name changes, every internal import path in every repo breaks at once, and fixing hundreds of repos in a coordinated way is effectively impossible.

The fix is to migrate into a temporary EMU org, then swap names:

Migrate everything to your-org-emu.
Rename the source org: your-org to your-org-legacy.
Rename the destination: your-org-emu to your-org.

The destination ends up with the original name, so nothing downstream changes. Even if you aren't a Go shop, the swap protects every hardcoded org reference in CI config, scripts, docs and service configuration.

Note

This isn't the right call for everyone. It depends on how deeply your org name is baked into your code, how much data you have, and how much risk you're willing to take. If references are few, renaming and fixing them gradually may be cheaper than a coordinated cutover. In this case the references were everywhere, so the risk of a single cutover event was accepted.

2. Build your own migration tooling

gh-gei fails non-deterministically at scale. At 1,000+ repos, some percentage of runs fail for reasons unrelated to the repo, and you won't have time to wait for support. The core of a git migration is simple:

# Clone the source as a bare mirror
git clone --mirror https://x-access-token:{token}@github.com/{source_org}/{repo}.git

# GitHub blocks pushing refs/pull/*, so fetch them under a different name
git config --add remote.origin.fetch '+refs/pull/*:refs/migrated-pull-request/*'
git fetch origin

# Push everything to the destination
git push --force --no-thin https://x-access-token:{token}@github.com/{dest_org}/{repo}.git --all
git push --force --no-thin https://x-access-token:{token}@github.com/{dest_org}/{repo}.git --tags

# LFS, if the repo has it
git lfs fetch --all
git lfs push --all https://x-access-token:{token}@github.com/{dest_org}/{repo}.git

The wrapper around it is where the reliability comes from:

Per-repo status tracking: succeeded, failed, skipped
Automatic retry with backoff
Commit-drift detection before any re-migration
A pool of GitHub Apps, one per concurrent job, so rate limits don't contend across repos
Ref batching (500 at a time, falling back to one-by-one for problem repos)
Incremental re-runs that skip refs already on the destination with matching SHAs

And validate with a separate framework. Don't trust the migration tool's own exit codes as github api can be very flaky.

What migrates and what doesn't

Item	Status
Commits, branches, tags, LFS objects, labels, releases	Full fidelity (draft releases excluded)
Pull requests and issues	Partial: authorship, reactions and assignees are lost, drafts become open PRs
Projects	Custom tooling; sort/group settings and automation workflows are lost
Discussions	Custom tooling; custom categories need browser automation
Actions secrets	Write-only API, needs its own strategy
Actions variables	Not migrated, but readable via API
GitHub Apps	Not transferable, must be reinstalled
Branch protections, rulesets, environments, teams	Not migrated, rebuilt after
Webhooks, deploy keys, runners, fork relationships	Not migrated
SSH keys	Not migrated, each engineer regenerates

Because surprises during the cutover (during the rename) are expensive, an audit of the source org came first, covering repos by visibility, LFS, wikis, Discussions, Projects, Apps and installation IDs, secrets (names only), webhooks, variables, runners and CODEOWNERS files. That inventory sized the tooling, flagged per-repo exceptions, and became the validation baseline.

The lessons that hurt

Secrets are three separate problems

GitHub's Secrets API is write-only. Nobody, including org admins, can read a value back. That applies to org secrets, repo secrets and Dependabot secrets, and each needs a different approach:

Org secrets: pre-populate each as a repo secret on a migration repo; a workflow reads them via env: and writes them to the destination org with gh secret set, preserving visibility.
Repo secrets: generate a per-repo workflow, push it to a branch, and trigger them all centrally with staggered delays.
Dependabot secrets: a separate API again. Source the values from the equivalent Actions org secrets or your secrets manager.

SSO and the rename must be simultaneous

Update the IdP configuration at the same moment as the rename. Any gap, and every user loses SSO access. This 15 to 30 minute window was the highest-risk part of the migration. This can be restored by Github Support if things go wrong still.

CODEOWNERS fail silently

EMU usernames follow a new format, and GitHub gives no error or warning when CODEOWNERS references unknown users. You just lose enforcement. Generate a username mapping CSV from your directory (LDAP/AD) early, since many downstream steps depend on it, then script a rewrite that opens and auto-merges a PR in every repo. Drop usernames with no EMU equivalent. Also note that Apps can't be code owners in EMU, so automation needs an EMU-managed service account.

Team Sync doesn't work with EMU

The Team Sync API returns 403 - This team is not externally managed. Use the External Groups API instead. If you use Terraform, swap github_team_sync_group_mapping for github_emu_group_mapping. And remember that your IdP groups must be explicitly assigned to the EMU Enterprise Application, or they simply won't appear and your mappings will silently come back empty.

Issue and PR numbers must not shift

Teams reference issue and PR numbers everywhere: Jira tickets, Confluence pages, commit messages, Slack threads. If the numbers shift during migration, every one of those references quietly points at the wrong thing, and nothing tells you.

They shift more easily than you'd expect. If an issue was deleted in the source, a naive migration just skips it, and every later number moves down by one. The fix is to migrate PRs and issues in ascending order and track the number you expect next. When there's a gap, create a placeholder issue to hold the slot, label it emu-gap-#number-of-issue and close it straight away. That way #42 in the source lands as #42 in the destination. Failures get the same treatment. If an item can't be migrated, an error placeholder holds its number and records the failure, instead of letting everything after it shift.

A few things to know:

Placeholders are inert. Exclude them from comment migration and relationship syncing.
They inflate your issue and PR counts, so validation should treat a count difference as a warning, not a failure.
For repos where numbers don't matter, such as high-volume repos full of machine-generated PRs, turn placeholders off. Thousands of them add nothing.

The small ones that bite

Wikis: the wiki repo can't be created via API, so content silently skips unless someone creates the first page in the destination by hand. Do it before the run.
Discussion categories: no API exists, so Playwright handled it, and the Discussions migration was gated on a script that compares source and destination categories.
Projects: gh migrate-project can't rotate tokens, and App tokens die after an hour, so large projects need to run sequentially with a classic PAT. Archive stale projects beforehand, screenshot view settings, and document automation workflows.
Actions variables: values are readable, so export and recreate via API.

Order of operations

The sequence mattered, and deviating from it created race conditions:

Lock the source org with rulesets so nothing can push.
Block IaC and operators that manage teams or repos.
Pause GitOps controllers.
Pre-create wiki repos in the destination.
Migrate repos in batches, validating each.
Migrate Projects and Discussions in parallel.
Run full validation and fix failures before the rename.
Rename source to -legacy, then destination to the original name.
Update the IdP immediately.
Repair: branch protections, CODEOWNERS PRs, App access.
Reconcile GitOps CRs.
Reinstall runners and reconnect integrations.
Validate services end to end.
Enable Actions and remove the blocking rulesets.
Tell engineers to regenerate SSH keys.

Validation

Parallelise from the start. With 40 workers, validating 1,300+ repos took about an hour, versus 2 to 4 hours sequentially. Checks covered commit counts, branch and tag SHAs, default branch, metadata, issue/PR/release counts, milestones, wiki presence, CODEOWNERS presence and discussion counts.

Then validate the services, not just the repos: submit test jobs on every runner type, resolve a module through the proxy, mint a token, confirm OIDC, and open a test PR to check code owner enforcement.

Rollback

Define abort criteria and decision authority before the cutover. Before the rename, rollback is clean: the source is read-only but intact, so you lift the rulesets, resume automation and reschedule. After the rename it's forward-fix only. The legacy org remains as a safety net (keep it for at least 3 months), and individual repos can be re-pushed from it. GitHub also imposes a waiting period between renames, so don't assume you can reverse one quickly. You need good coordination with GitHub Support for this rename process and I'd recommend getting them involved early.

Running an EMU migration?

There's a thousand more things you need to think about

terraform state files
flux cd/ argo cd reconfiguration
github apps
github runners
ip allowlists
github settings
github team memberships and roles ... list goes on and on

There's a lot more I could add to this post, but if you're running an EMU migration and want help working through the decisions, I'm always up for a coffee or a call. I'm based in Melbourne, and you can DM me on LinkedIn.

https://www.linkedin.com/in/pulkit07/

Glossary

CRs: custom resources (the Kubernetes objects that GitOps operators manage)
EMU: Enterprise Managed Users
gh-gei: the GitHub CLI extension for GitHub Enterprise Importer (GEI), GitHub's own migration tool
IaC: infrastructure as code
IdP: identity provider
LDAP/AD: Lightweight Directory Access Protocol / Active Directory
LFS: Large File Storage (Git LFS)
OIDC: OpenID Connect
PAT: personal access token

Other Great Source to Read: https://github.com/orgs/community/discussions/189382

DEV Community: Pulkit Aggarwal