How to mirror push in Git
Łukasz Holeczek
Follow Łukasz Holeczek on GitHub
Connect with Łukasz Holeczek on LinkedIn
Follow Łukasz Holeczek on X (Twitter)
Mirror pushing copies all refs - branches, tags, and notes - from one repository to another, keeping them in perfect sync.
As the creator of CoreUI with over 25 years of version control experience since 2000, I’ve used mirror pushes for backup strategies, repository migrations, and maintaining read-only mirrors for different teams.
The standard approach adds a secondary remote and pushes with --mirror to replicate everything exactly.
This ensures the destination is an exact copy of the source.
Push all refs to a mirror repository.
git remote add mirror https://gitlab.com/username/repo.git
git push mirror --mirror
--mirror pushes all branches, tags, and notes. It also deletes refs on the destination that no longer exist in the source. The destination becomes a perfect clone of the source.
Setting Up a Permanent Mirror Remote
Configure push to mirror automatically.
git remote add mirror https://gitlab.com/username/repo.git
git remote set-head mirror --auto
git config remote.mirror.mirror true
git push mirror
Setting remote.mirror.mirror true makes every git push mirror behave as --mirror. No need to remember the flag each time.
Mirroring During a Remote URL Change
Use mirror push when moving to a new hosting provider.
git clone --bare https://github.com/username/old-repo.git
cd old-repo.git
git push --mirror https://gitlab.com/username/new-repo.git
Clone bare for a complete copy without working tree. Push mirror to the new URL transfers everything. The new repo has identical history, branches, and tags.
Automating with a Script
Schedule regular mirror syncs.
#!/bin/bash
# mirror-sync.sh
cd /path/to/repo
git fetch origin
git push mirror --mirror
echo "Mirror synced at $(date)"
Run this via cron to keep the mirror current. git fetch origin updates from the primary remote. The mirror push propagates all changes. Schedule with */30 * * * * /path/to/mirror-sync.sh for every 30 minutes.
Pushing to Multiple Remotes
Push to several destinations simultaneously.
git remote set-url --add --push origin https://github.com/username/repo.git
git remote set-url --add --push origin https://gitlab.com/username/repo.git
git push origin
--add --push adds a second push URL to an existing remote. A single git push origin now pushes to both destinations. This is simpler than maintaining a separate mirror remote.
Best Practice Note
This is the same mirror strategy we use for CoreUI repository backups across multiple hosting providers. Always verify the mirror after the first push by cloning from it and checking branch counts match. Mirror pushes delete remote branches that no longer exist locally, which is intentional for mirroring but destructive if you accidentally push to the wrong remote. Double-check your remote URLs before pushing with git remote -v. For CI/CD pipelines, use deploy keys with limited permissions for the mirror remote to minimize security exposure.
