GitHub Backup Sync
Mirror every GitHub repository you can access into local git backups.
Authenticated through the GitHub CLI, so there are no tokens to juggle.
github-backup-sync mirrors every GitHub repository your account can access (owned, collaborator, and organization member) into bare --mirror clones, grouping sources and forks separately.
The project was inspired after watching ThePrimeTime's reminder about GitHub bans, highlighting why local backups matter.
Plenty of alternative backup tools exist, but I wanted something simple that relies on the GitHub CLI for authentication so I never have to juggle API tokens directly.
Table of Contents
Features
- Complete mirrors: bare
git clone --mirror copies keep every branch, tag, and ref; re-runs update them in place.
- Sources and forks apart: forks land in their own directory, or skip them entirely with
--skip-forks.
- No token management: the token comes from
gh auth token, so staying logged in to the GitHub CLI is all it takes.
- Fast: repositories sync in parallel (
--workers).
- Safe pruning: mirrors of repositories that disappeared upstream are listed on every run and only deleted with
--prune.
- Flexible: optional working-tree checkouts, Git LFS objects, and archived-repository filtering.
- Single file: one script with a
uv run --script shebang, so you can also vendor it anywhere.
Quick Start
gh auth login # once
uvx github-backup-sync --root ~/github-backups # mirror everything
Run the same command again whenever you want to pull in new commits, branches, and repositories.
Requirements
uv (recommended) or any Python 3.12+ environment
- GitHub CLI (
gh) authenticated with gh auth login
git, plus git-lfs if you use --lfs
- SSH access to GitHub for the default SSH remotes, or pass
--https
Installation
| Method |
Command |
| Run without installing |
uvx github-backup-sync --help |
| Install as a tool |
uv tool install github-backup-sync |
| Install with pip |
pip install github-backup-sync |
| Vendor the script |
Copy github_backup_sync.py and run ./github_backup_sync.py |
uvx fetches the latest release on each run, while uv tool install puts a github-backup-sync executable on your PATH.
The vendored script installs its own dependencies through the uv run --script shebang.
Usage
# If installed from PyPI
github-backup-sync --root /path/to/mirrors [--https] [--prune] [--skip-forks] [--workers 4]
# From a local checkout
./github_backup_sync.py --root /path/to/mirrors [--https] [--prune] [--skip-forks] [--workers 4]
Options
| Option |
Description |
-r, --root PATH |
Backup directory (required, created if missing) |
--https |
Use HTTPS remotes instead of SSH, authenticated through the GitHub CLI |
--prune |
Delete local mirrors that no longer exist upstream; without it they are only listed |
--working-tree / --bare |
Clone with files checked out instead of bare mirrors (default: --bare) |
--include-archived / --exclude-archived |
Whether to back up archived repositories (default: include) |
--skip-forks |
Mirror only non-fork repositories |
--lfs |
Fetch Git LFS objects after mirroring |
-w, --workers N |
Parallel sync operations (default: CPU count, capped at 8) |
--sleep SECONDS |
Delay between repositories |
--limit N |
Process at most N repositories, handy for smoke tests |
[!TIP]
With --https, git asks gh auth git-credential for the token on demand, so it is never written to a mirror's config or visible in the process list.
Mirrors created by versions before 0.2.1 stored the token in their remote URL; the next sync rewrites it to a plain URL.
[!NOTE]
In --working-tree mode every run checks out the default branch and hard-resets it to origin, discarding local edits.
Treat those checkouts as read-only copies.
CLI Help
github_backup_sync.py --help output
Usage: github_backup_sync.py [OPTIONS]
Mirror every GitHub repository you can access into local git mirrors.
╭─ Options ──────────────────────────────────────────────────────────────────────────────────────────────────╮
│ --root -r <path> Directory that will hold the mirror │
│ --https <bool> Use HTTPS remotes, authenticated │
│ through the GitHub CLI │
│ --include-archived --exclude-archived <bool> Include archived repositories │
│ [default: include-archived] │
│ --prune <bool> Remove local mirrors that no longer │
│ exist upstream │
│ --lfs <bool> Fetch Git LFS objects after │
│ mirroring │
│ --working-tree --bare <bool> Clone repositories as working trees │
│ instead of bare mirrors │
│ [default: bare] │
│ --sleep <float range> [x>=0.0] Delay between repositories in │
│ seconds │
│ [default: 0.0] │
│ --limit <int range> [x>=1] Process at most this many │
│ repositories │
│ --skip-forks <bool> Ignore forked repositories while │
│ mirroring │
│ --workers -w <int range> [x>=1] Max concurrent mirror operations │
│ (default: based on CPU count) │
│ --help -h <bool> Show this message and exit. │
╰────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
Layout
<root>/source/<owner>/<repo>.git
<root>/forks/<owner>/<repo>.git
This is the default layout when backing up as bare mirrors.
When --working-tree is used, the .git suffix is omitted and each directory contains a checked-out working tree instead.
Working with Mirrors
Repositories under source/ and forks/ are bare --mirror clones, so they do not contain a checked-out working tree unless you opted into --working-tree.
Clone from a mirror path when you want editable files:
git clone /srv/github-backups/source/basnijholt/dotfiles.git ~/dotfiles
You can also inspect a mirror directly without cloning by pointing Git commands at it:
git --git-dir=/srv/github-backups/source/basnijholt/dotfiles.git log --oneline
Automated Backups (cron)
Schedule a daily sync with cron:
0 3 * * * /usr/bin/env uvx github-backup-sync --root /srv/github-backups --https --prune --workers 4 >> /var/log/github-backup-sync.log 2>&1
This example runs every day at 03:00, prunes mirrors of deleted repositories, and logs the output.
The cron user needs uv on its PATH and a logged-in gh.
Adjust the path, flags, and worker count to suit your environment.
License
MIT