gh-backup 0.3.0

Backup a GitHub organization or user: repos, issues, and pull requests

gh-backup

Backup a GitHub organization or user: repos, issues, and pull requests.

Clones all repositories with full git history and exports issues/PRs as JSON, then compresses everything into a .tar.zst archive.

Requirements

• GitHub CLI (gh) — authenticated with a token that has repo and read:org scopes

Installation

# uv (recommended)
uv tool install gh-backup

# pip
pip install gh-backup

# pipx
pipx install gh-backup

Authentication

gh-backup auth

Checks that gh is authenticated and reports the active account and token scopes.

Usage

Export an organization

gh-backup export myorg --output /backups

Export a user account

gh-backup export myusername --output /backups

Account type (org or user) is detected automatically.

Options

Option	Short	Description
--output PATH	-o	Directory to write exports into (required)
--workers N	-w	Parallel clone workers (default: 4, max: 32)
--repos NAME	-r	Only export specific repos (repeatable)
--format		Archive format: zst (default), gz, or xz
--no-compress		Keep raw export directory, skip archiving
--keep-dir		Keep uncompressed directory after archiving
--shallow		Shallow clone (--depth 1); faster but no full history
--gc		Run git gc --aggressive on each clone to shrink pack files
--dry-run		List repos that would be exported without writing anything
--skip-forks		Exclude forked repositories
--skip-archived		Exclude archived repositories
--visibility		Only export repos with this visibility: all (default), public, or private
--skip-issues		Skip issues and pull request export
--verbose	-v	Enable debug logging

Examples

# Export an org with more workers
gh-backup export myorg --output /backups --workers 8

# Export specific repos only
gh-backup export myorg --output /backups --repos frontend --repos backend

# Export a user account, skip issues, no compression
gh-backup export myusername --output /backups --skip-issues --no-compress

# Export with GZ compression instead of ZST
gh-backup export myorg --output /backups --format gz

Each run is saved to a timestamped subdirectory under the output directory, then compressed into a single archive.

Output structure

The archive unpacks to:

<org>-<timestamp>/
├── metadata.json       # Export config and repo stats
├── repos/
│   ├── repo1.git       # Bare mirror clone (git clone --mirror)
│   └── ...
└── issues/
    ├── repo1/
    │   ├── issues.json
    │   └── pulls.json
    └── ...

Exit codes

Code	Meaning
0	Success
1	Export failed
2	Partial failure — some repos failed, others succeeded
130	Cancelled with Ctrl+C

Development

Requires uv.

make install    # Install dependencies and set up pre-commit hooks
make test       # Run the test suite
make lint       # Check linting and formatting (ruff)
make lint-fix   # Auto-fix linting and formatting issues
make commit     # Create a conventional commit (via commitizen)