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.

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

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

CLI Help

 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                                                               Use HTTPS remotes, authenticated     │
│                                                                       through the GitHub CLI               │
│ --include-archived      --exclude-archived                            Include archived repositories        │
│                                                                       [default: include-archived]          │
│ --prune                                                               Remove local mirrors that no longer  │
│                                                                       exist upstream                       │
│ --lfs                                                                 Fetch Git LFS objects after          │
│                                                                       mirroring                            │
│ --working-tree          --bare                                        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                                                          Ignore forked repositories while     │
│                                                                       mirroring                            │
│ --workers           -w                        <int range> [x>=1]      Max concurrent mirror operations     │
│                                                                       (default: based on CPU count)        │
│ --help              -h                                                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