GitHub Community
Moving Day: A Guide for Migrating Between GitHub Products 🚚📦 #191235
Replies: 1 comment
-
|
Hi, This is actually a really well-written guide — the “moving house” analogy makes it much easier to follow than most migration docs. A few thoughts from a practical standpoint: 1. The “Rename and Swap” advice is probably the most valuable part 2. Calling out what GEI does not migrate is important
Many teams assume everything moves automatically, so highlighting the 3. The 5,000 repo limit is a good early warning 4. One suggestion to improve the guide 👉 “Do a full dry run with 1–2 complex repositories before committing to the full migration.” You mentioned trial runs, but stressing it as mandatory (not optional) would help teams avoid surprises. 5. Real-world addition that could help readers
Because technically everything might go well, but coordination is usually what causes friction. Overall Definitely a helpful post for anyone planning a migration 👍 |
Beta Was this translation helpful? Give feedback.
Uh oh!
There was an error while loading. Please reload this page.
Uh oh!
There was an error while loading. Please reload this page.
-
Migrating an entire organization’s worth of data isn’t just a technical task - it’s like moving into a new home. Whether you’re consolidating your "furniture," leveling up your security with GitHub Enterprise Cloud (GHEC), or moving from a Server instance to the cloud, the goal is always the same: zero broken boxes and minimal developer friction. 🎯
While the GitHub Enterprise Importer (GEI) is the heavy-lifting "moving truck" for these shifts, a truly professional move requires looking beyond just the boxes of code. In this post, we’re breaking down the essential strategies for a seamless "Moving Day," including how to handle the items GEI leaves behind and the safest way to keep your organization’s identity intact.
1. Check the Size of Your "Truck": The 5,000 Rule 📊
Before you start packing, you need to audit your inventory. GEI is incredibly efficient for organization-level moves, but it has a specific weight limit: 5,000 repositories.⚠️ IMPORTANT: This is a hard limit. If your organization is larger than that, don't panic! You’ll simply need to pivot to a repository-level migration approach (think of it as hiring a second truck). Planning for this upfront prevents mid-move breakdowns and keeps your timeline on track.
2. Packing the "Fragile" Items: Specialized Tooling 🛠️
GEI is excellent at moving the "big furniture": repositories, issues, PRs, and commit history. But what about the small, fragile items that fill the spaces in between?
Many teams are surprised to find that items like GitHub Packages, Organization Secrets, and Webhooks don't automatically make it onto the truck. To solve this, the GitHub Services team maintains a suite of specialized tools - our "professional packers" - under the mona-actions organization.
Essential "Packing" Tools:
📦 gh-migrate-packages: Ensures your internal npm, Docker, or Maven registries arrive safely at the new address.
🔐 gh-migrate-variables: Don't make your developers manually re-label hundreds of Actions secrets.
🪝 gh-migrate-webhooks: Ensure your CI/CD and Slack integrations aren't left behind at the old house.
🔍 gh-migration-validator (Post-Migration Audit): Your final walkthrough tool to ensure every box that left Side A actually landed on Side B.
Note
Pro-tip: Most of these are GitHub CLI extensions. You can get started with a simple:
gh extension install mona-actions/gh-migrate-packages3. The "Rename and Swap": Getting the Keys 🏷️
One of the biggest hurdles is the "Namespace Problem." Organization names on GitHub.com are like street addresses - they must be globally unique. If you want to move Acme-Corp to a new Enterprise account while keeping the name Acme-Corp, you can't just move in while the old house still has the sign up.
🚨 Avoid the "Big Bang" Move 🚨
Some teams attempt a "big bang" move:
Warning
This is EXTREMELY HIGH RISK.
This approach has zero failure tolerance. If even ONE repository fails to migrate, you’re stuck in "namespace limbo" with some repository in one namespace and other in another, bringing broken links, no way to verify your data, and no easy way back to the old place.
The "Rename and Swap" strategy
The approach for a big bang migration is to move into your new place with a "temporary key" first.
Visual Guide: The Migration Sequence
![Insert "Rename and Swap" Sequence Diagram Here]
Fig 1. The recommended workflow for migrating data to a temporary namespace before swapping the final organization name.
Move to a Temporary Address: Migrate Acme-Corp to Acme-Corp-Cloud.
The Walkthrough: Use this window to run your tests, check your secrets, and validate that nothing was damaged in transit.
Release the Old Title: Rename the original Acme-Corp to Acme-Corp-Archive. This releases the name to the public.
Change the Sign: Immediately rename Acme-Corp-Cloud to Acme-Corp.
Note
Avoid deleting the "old" organization namespace as you won't be able to reclam this for 90 days
📌 Note: Be aware of Namespace Retirement. If your original house was "historic" (had high activity), GitHub might "retire" the name for security. You may need to reach out to GitHub Support to "un-retire" it during your moving window.
4. Your Moving Day Checklist ✨
A successful move is 80% prep work. Here is your high-level roadmap:
[ ] Inventory: Identify your repo count and the "fragile" data (secrets, packages).
[ ] Permissions: Ensure you have the "keys" (Owner access) for both the source and the destination.
[ ] Trial Run: Always move a few test boxes (complex repos) first to see how they handle the trip.
[ ] Forwarding Address: Give your developers a clear "read-only" window so no new work is done at the old house during the move.
[ ] Unpack the Metadata: Use mona-actions to move the items GEI skips.
[ ] Final Audit & Swap: Confirm integrity with gh-pma, then execute your name swap.
Wrapping Up 🏁
Moving Day is a major milestone in an organization’s DevOps journey. By combining the heavy-lifting power of GEI with the specialized "packing" of mona-actions, you can turn a high-stress relocation into a smooth upgrade.
Have you recently managed a "Moving Day" between GitHub products? Share your best packing tips or your favorite mona-actions tool in the comments below! 👨💻
This guide was inspired by the Comprehensive Migration Guide authored by @rudy750 and @amenocal.
Note
Just like city codes and moving regulations, these tools and approaches evolve quickly. Before you start loading the truck, be sure to check the latest documentation for the most up-to-date blueprints. If you find yourself needing a hand with the heavy lifting, the Expert Services team is always happy to help you settle into your new home!
Expand the table below for helpful tools
Helpful Tool Guide
Legend
This guide was written with ❤️ by GitHub Customer Success and Expert Services.
Beta Was this translation helpful? Give feedback.
All reactions