The Tool Desk
Outbyte PC Repair FREERepair Windows errors before they cause bigger problemsFix Now →Outbyte Driver Updater FREEScan for outdated or missing drivers - takes under a minuteDriver Scan →Move a monorepo as a controlled cutover, not a one-time push. Back up every Git object, recreate hosting and CI settings, rehearse the migration, keep one canonical writer during a short freeze, compare refs, then switch developer remotes while the old repository remains read-only for rollback.
What a safe monorepo migration actually moves
A Git repository contains commits, trees, blobs, branches and tags. Your hosting service contains a separate layer of operational data: permissions, protected refs, pull or merge requests, issue history, webhooks, runners, secrets, environments, package registries, releases and audit settings. A mirror push can preserve Git objects while leaving that second layer empty.
As an Amazon Associate I earn from qualifying purchases.
Plan the migration as two linked workstreams:
- Repository data: every required branch and tag, annotated tag objects, commit history, Git LFS content, submodule references and any custom refs used by automation.
- Hosting and delivery: teams, access levels, branch and tag protections, required status checks, CI configuration, variables, secrets, runners, deploy keys, hooks, webhooks, environments, registries, releases and collaboration history.
The success condition is not merely “the destination cloned.” Developers must be able to clone, build representative projects, run tests, publish packages and deploy through the destination with the same controls they had before.
Define the invariants before touching the source
Write a migration checklist that can be verified objectively. At minimum, record:
#1 Best Overall
- The canonical default branch and its expected tip commit.
- Every release, long-lived and support branch, including branches not visible in the default UI.
- The complete tag set, noting whether each tag is annotated or lightweight.
- Git LFS-tracked paths and the expected LFS object count or verification result.
- Submodule URLs and the commit each submodule must resolve to.
- Required status checks, CODEOWNERS rules, deploy keys and external automation.
- CI runners, environments, variables, secrets, package registries, releases, webhooks and integrations.
Turn those records into pass/fail invariants. Critical branch tips and release tags must have identical object IDs at both hosts. A clean clone must succeed using the new URL. A representative change in each major monorepo area must trigger the intended pipeline, and an unrelated change must not trigger work that path rules are designed to exclude. The rollback route must be documented before the freeze begins.
Build an inventory that includes hidden dependencies
Inspect refs and tags
Use a fresh working copy or a machine dedicated to the migration. List all local and remote refs, not only branches shown in the web interface:
git ls-remote --heads --tags <source-url> > source-refs.txt
git show-ref > local-refs.txtFor annotated tags, verify the tag object as well as the commit it points to. A tag that appears correct in a browser can still lose its annotation or signature if it was recreated rather than transferred.
Find LFS and submodule requirements
Search the repository configuration and history for LFS tracking and submodules:
git lfs ls-files
git config --file .gitmodules --get-regexp 'path|url'Record whether submodule URLs are reachable by the same identities developers and CI will use after the move. If a submodule is private, its deploy key or access token must be recreated at the destination or in the consuming pipeline.
Inventory hosting metadata
Export or record, in a controlled location, the following items:
- Organization, group, project and repository namespaces.
- Human users, teams, service accounts and their access levels.
- Protected branches and tags, merge permissions, approval rules and required checks.
- CI variables and secrets, runner assignments, environment protection and deployment approvals.
- Webhooks, deploy keys, signing keys, scheduled jobs and external status reporters.
- Package registries, container images, releases, release assets and retention rules.
- Issues, merge or pull requests, comments, labels, milestones and activity history if those records are required.
File exports can preserve much project data but may omit records or alter access levels. For a move between projects on the same hosting platform, use the platform’s direct transfer mechanism when available; otherwise validate collaboration history as a separate migration stream rather than assuming a Git import carries it.
Create and verify a complete backup
Make a new mirror clone from the source and keep it isolated and immutable until the rollback window closes:
Rank #2
- Used Book in Good Condition
git clone --mirror <source-url> monorepo.git
cd monorepo.git
git show-ref
git fsck --fullA mirror clone copies the repository’s refs and revision history, including references that an ordinary working clone may not fetch. Store it on protected, access-controlled storage. Do not put credentials in command history, scripts committed to the repository or CI logs; use a credential helper, short-lived token or protected secret injection instead.
Verify the backup against the source
Compare the expected branch and tag tips from the source with the mirror. Check that every LFS object is present:
git lfs fetch --all
git lfs fsckThe exact LFS verification output depends on the installed LFS version, but missing objects must be treated as a failed backup, not as a warning. Test recoverability by pushing the mirror to a disposable, empty repository:
Recommended Free Tools
git push --mirror <disposable-destination-url>Delete the disposable destination after validation if it contains sensitive data. The test proves that the backup is usable for restoration; an archive generated by a hosting migration UI is not automatically a supported restore mechanism.
Build the destination before the cutover
Create an empty repository in the final namespace with the intended default branch policy. Do not invite developers to use it as a second active source while it is being prepared. Recreate the controls and integrations from the inventory:
- Groups, teams, service accounts and least-privilege access.
- Protected branches and tags, approval rules, merge permissions and required status checks.
- Deploy keys, signing keys, webhooks and external integrations.
- Runners, runner tags, environments, deployment approvals and concurrency limits.
- CI variables, secrets, package and container registries, release settings and retention policies.
- CODEOWNERS and repository-level configuration that the host does not receive from Git objects.
Import the mirror only after these controls exist, or apply them immediately afterward while the destination is inaccessible to normal writers. Check whether the destination supports the same object format as the source. Repository mirroring requires matching object formats; an incompatible format needs a different transfer method.
Rehearse with a dry run
Run a dry migration for every repository, including this monorepo. GitHub’s migration guidance explicitly recommends a dry run for every repository because it exposes missing permissions, unsupported metadata and oversized transfers before the production window.
- Push the mirror to a disposable destination or an isolated namespace.
- Apply the intended branch and tag protections, teams, runners, secrets and integrations.
- Clone the disposable destination from a clean machine using the same authentication method developers will use.
- Build and test representative paths: for example, one service, one shared library, one frontend or tooling project, and the packaging or deployment jobs that consume them.
- Open a test change and confirm path filters, child pipelines, approvals, status checks, artifact publication and deployment gates.
- Compare refs, tags, LFS files and submodule checkouts with the source.
Record each failure and its owner. A rehearsal is complete only when the same acceptance checks pass from a clean clone, not when the import command reports success.
Rank #3
Bridge the old and new locations safely
Choose one canonical writer
During preparation, designate exactly one repository as authoritative for writes. Developers may read the other location, but merges, tag creation, release automation and jobs that update refs must target the canonical writer. Two active writers create divergent branches and ambiguous “last change” decisions.
Use mirroring for the preparation period
When the hosting platform supports it, configure push, pull or bidirectional repository mirroring. Branches, tags and commits can be synchronized automatically, and some services let you limit mirroring to protected branches. Mirror all required refs unless you have deliberately documented a narrower set.
Monitor mirror status and alert on failures. A divergent downstream branch can stop updates. If overwrite behavior is enabled, the upstream copy can replace downstream-only changes; that setting is appropriate only when the downstream is intentionally noncanonical and everyone accepts the risk of losing its commits. Never use overwrite to conceal an unreviewed divergence.
Prevent accidental writes on the noncanonical side
Remove merge permissions, disable release jobs and pause scheduled automation on the noncanonical repository. Add a visible notice explaining which URL accepts writes. A mirror is a bridge, not permission management; users who can write directly can still create a divergence that the bridge cannot safely resolve.
Prepare monorepo CI for the new host
Migration is an opportunity to preserve delivery speed without cloning the entire monorepo for every job. Evaluate each choice against history completeness, checkout bandwidth, CI latency, tooling compatibility and operational complexity.
| Technique | What it changes | Trade-off | Good fit |
|---|---|---|---|
| Full clone | Downloads complete history and objects. | Highest transfer and storage cost. | History-intensive tools, release jobs and debugging. |
| Shallow clone | Limits commit depth with options such as --depth 1. |
Breaks or limits tools that need older commits, merge bases or full blame history. | Short-lived test jobs that need only the current tree. |
| Partial clone | Uses a filter such as --filter=blob:none to defer objects. |
Requires server, client and tooling support; missing objects are fetched on demand. | Large histories where jobs touch a predictable subset of files. |
| Sparse checkout | Materializes only selected directories in the working tree. | Builds that cross directory boundaries need an accurate sparse definition. | Path-isolated projects in a large monorepo. |
| Workspace reuse | Runs git fetch in an existing workspace instead of recloning. |
Requires cleanup, isolation and protection against stale generated files. | Stable, trusted runners with controlled concurrency. |
Use path-aware pipelines
Configure rules so a change under one application or library starts only the jobs that can be affected. For larger trees, split work into child pipelines or equivalent downstream workflows. Define the path-to-pipeline map explicitly and test changes at directory boundaries, shared libraries and root-level build files. A root configuration change often affects every project and should intentionally bypass narrow path filters.
Reduce unnecessary concurrency
Set concurrency limits so duplicate pipelines do not consume every runner during a migration. Cancel superseded branch pipelines where that policy is safe, but keep deployment and release jobs protected from cancellation. Use shallow or partial clones and sparse checkout only after validating that test tools, code generation and versioning commands still have the history and files they require.
Free tools Windows power users keep installed
One-click scans. No signup required.
Schedule the production cutover
Choose a low-traffic UTC window and announce a short, precise write freeze. State the start and end times, the canonical URL during the freeze, who can approve an emergency exception and where status updates will appear. The freeze should cover:
Rank #4
- Merge and pull requests, direct pushes and tag creation.
- Release jobs and automation that writes branches, tags or generated files.
- Scheduled pipelines, bots and external systems that update repository refs.
Developers can continue local work during the freeze, but they must not push to either host. Ask them to keep unpushed commits safely on local branches and to avoid rebasing shared work until the new remote is confirmed.
Execute the final synchronization
- Stop writers. Disable merges, direct pushes, release automation and scheduled jobs on the source or enforce the freeze with temporary protections.
- Run the final mirror update. Confirm the bridge reports a successful synchronization, or run the final mirror push from the isolated backup.
- Compare critical refs. Capture branch and tag tips from both hosts and compare object IDs. Any difference requires investigation before proceeding.
- Check dependent objects. Fetch or verify LFS content, clone required submodules and confirm release assets and package metadata.
- Run acceptance pipelines. Execute representative builds, tests, packaging and deployment checks on the destination with clean credentials and runners.
- Switch the documented URL. Publish the new clone URL and migration status page only after the destination passes the checks.
- Re-enable destination writers. Restore merges, release jobs and scheduled automation on the destination; leave the source read-only.
For a manual mirror push, the repository command is:
git push --mirror <new-destination-url>Do not use a normal branch-by-branch push when preserving all refs is a requirement; it is easy to omit tags, remote-tracking refs or less visible branches.
Quick wins for a faster PC:
Repair Windows errors before they cause bigger problemsFix Now →Fix the driver behind crashes, sound loss and screen glitchesFind Drivers →Switch developers without forcing a reclone
Most working copies can change their remote in place:
git remote -v
git remote set-url origin <new-url>git remote -v
git fetch --prune originUse the host’s equivalent tooling if it manages remotes centrally. Developers should verify that origin points to the destination, fetch, and then push a small test branch if policy permits. Existing local branches and uncommitted files are not changed by git remote set-url, but a branch may still track an old remote branch. Check tracking with:
git branch -vvUpdate tracking deliberately, for example:
git branch --set-upstream-to=origin/<branch> <branch>Do not delete the old remote URL from documentation, scripts or deployment systems until those consumers have been migrated. Search CI configuration, build scripts, dependency manifests and local setup instructions for the old hostname.
Validate operations after the switch
Monitor the destination closely during the rollback window. Check:
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
- Clone and fetch errors, authentication failures and unexpectedly slow transfers.
- Pipeline queue time, runner availability, cache behavior, path filters and child-pipeline fan-out.
- Webhook delivery, required status checks, merge approvals and protected-ref enforcement.
- Package publication, release assets, container pushes and deployment jobs.
- Submodule access, LFS downloads, signing or verification failures and external integrations.
- Missing users, teams, permissions, issues, merge requests, comments or activity history.
Keep a short-lived support channel with an owner who can classify incidents as repository-data, permission, CI, integration or developer-configuration problems. Capture the exact URL, ref, job and error message for each report; “the migration is broken” is not enough to locate a failed layer.
Best Value
Rollback without losing new work
Leave the source repository read-only and clearly marked as archived until the destination has passed operational checks and the agreed rollback period has ended. If a critical defect appears, stop destination writes first. Preserve any destination commits created after cutover, compare them with the source, and decide whether to transfer those commits back through a controlled process or discard them with explicit approval. Then redirect developers to the old remote and restore its CI and integrations.
Never make both repositories writable during rollback. That recreates the split-brain condition the freeze was designed to prevent. Once the destination is fixed and validated, repeat the final-sync and remote-switch steps with a new freeze window.
Common failure modes and fixes
A branch exists on one host only
Stop the cutover and identify which side is canonical. Export the missing commit range, review it, and update the canonical repository before repeating ref comparison. Do not enable overwrite mirroring to hide the discrepancy.
Windows Errors? Fix Them Before They Spread
Repair common Windows errors and clear accumulated junk for a smoother, more stable PC - no reinstall needed.Free scan · no reinstallOutdated Drivers Are Slowing You Down
One free scan finds every outdated or missing driver and matches the right update for your exact hardware.Free scan · exact hardware matchTags have the right names but wrong objects
Compare tag object IDs and peeled commit IDs, not just names. Re-transfer the original tag refs from the mirror and verify signatures or release automation that depends on annotated tags.
LFS files clone as pointers
Check LFS authentication and object availability on the destination, run the LFS verification commands against the mirror, and ensure CI runners have the LFS client and credentials. A successful Git ref transfer does not prove that large-file objects transferred.
CI runs every project for every change
Review path rules, root-level dependency detection and child-pipeline triggers. Test a change confined to one project, a shared-library change and a root configuration change. Add explicit rules for each case rather than relying on filename conventions that differ between hosts.
Developers can clone but cannot merge or deploy
Compare team membership, protected-ref rules, required checks, environment approvals, deploy keys and secrets. Repository object history is intact in this case; the missing layer is hosting configuration.
Do these 3 things before closing this tab:
1Repair Windows errors before they cause bigger problems2Scan for outdated or missing drivers - takes under a minute3Clear out junk files and repair common Windows errorsThe mirror stops updating
Inspect the mirror status for a divergent downstream ref, authentication failure or incompatible object format. Make one side canonical, resolve or remove unauthorized downstream changes, and restart synchronization only after the ref policy is explicit.
Quick Recap
Completion checklist
- Mirror backup is stored immutably, verified with ref and LFS checks, and restored successfully to a disposable destination.
- All required branch and tag tips match between source and destination.
- Teams, permissions, protections, secrets, runners, hooks, webhooks, environments, registries and releases are recreated and tested.
- Dry-run builds, tests, package publication and deployment checks pass from clean clones.
- One canonical writer is documented; the other location rejects writes.
- Final synchronization occurred inside a published UTC freeze window.
- Developer remotes, CI scripts and external automation use the new URL.
- Monitoring and rollback owners are assigned, and the old repository remains read-only through the rollback period.
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
