gitbackup - Backup your GitHub, GitLab, Bitbucket, and Forgejo repositories

Code Quality

Commerical Support

As of February 2026, Common Loop Works Pty Ltd, a software development, machine learning and cloud advisory company, founded by Amit Saha supports commercial development and support of gitbackup. Contact us for any custom on-prem or cloud deployment, new feature requests or expedite any bug fixes.

User guide

• gitbackup - Backup your GitHub, GitLab, Bitbucket, and Forgejo repositories
  • Introduction
  • Installing gitbackup
    • Docker image
  • Using gitbackup
    • GitHub Specific oAuth App Flow
    • OAuth Scopes/Permissions required
      • Bitbucket
      • GitHub
      • GitLab
      • Forgejo
    • Security and credentials
    • Configuration file
    • Examples
      • Backing up your GitHub repositories
      • Backing up your GitLab repositories
      • GitHub Enterprise or custom GitLab installation
      • Backing up your Bitbucket repositories
      • Backing up your Forgejo repositories
      • Specifying a backup location
      • Cloning bare repositories
      • GitHub Migrations
  • Building

Introduction

gitbackup is a tool to backup your git repositories from GitHub (including GitHub enterprise), GitLab (including custom GitLab installations), Bitbucket, or Forgejo.

gitbackup currently has two operation modes:

• The first and original operating mode is to create clones of only your git repository. This is supported for GitHub, Gitlab, Bitbucket, and Forgejo.
• The second operating mode is only available for GitHub where you can create a user migration (including orgs) which you get back as a .tar.gz file containing all the artefacts that GitHub supports via their Migration API.

If you are following along my Linux Journal article (published in 2017), please obtain the version of the source tagged with lj-0.1.

Installing gitbackup

Binary releases are available from the Releases page. Please download the binary corresponding to your OS and architecture and copy the binary somewhere in your $PATH. It is recommended to rename the binary to gitbackup or gitbackup.exe (on Windows).

If you are on MacOS, a community member has created a Homebrew formula.

Docker image

Docker images are published to GitHub Container Registry on every release:

docker pull ghcr.io/amitsaha/gitbackup:<version>

Replace <version> with the desired release tag (e.g. 0.9.1).

The container runs as a non-root user (nonroot, UID 65532). HTTPS cloning (-use-https-clone) is recommended inside containers because it requires no SSH key management.

Linux

On Linux, Docker runs natively so container UIDs map directly to host UIDs. Before mounting a backup directory, grant write access to UID 65532:

mkdir -p /data/gitbackup
chown 65532:65532 /data/gitbackup

Run with HTTPS cloning (recommended):

docker run --rm \
  -e GITHUB_TOKEN=<your-token> \
  -v /data/gitbackup:/backup \
  ghcr.io/amitsaha/gitbackup:<version> \
  -service github -backupdir /backup -use-https-clone

If you need SSH cloning, make a copy of your private key readable by UID 65532 and mount it:

cp $HOME/.ssh/id_rsa /tmp/gitbackup_id_rsa
chown 65532 /tmp/gitbackup_id_rsa
chmod 600 /tmp/gitbackup_id_rsa

docker run --rm \
  -e GITHUB_TOKEN=<your-token> \
  -v /data/gitbackup:/backup \
  -v /tmp/gitbackup_id_rsa:/home/nonroot/.ssh/id_rsa:ro \
  -v $HOME/.ssh/known_hosts:/home/nonroot/.ssh/known_hosts:ro \
  ghcr.io/amitsaha/gitbackup:<version> \
  -service github -backupdir /backup

macOS

Docker Desktop for Mac runs containers inside a Linux VM and translates volume mounts through its filesystem layer (VirtioFS). Because of this translation, the container UID (65532) is mapped automatically — you do not need to chown the host directory. Paths use the same Unix syntax as Linux.

mkdir -p $HOME/gitbackup

docker run --rm \
  -e GITHUB_TOKEN=<your-token> \
  -v $HOME/gitbackup:/backup \
  ghcr.io/amitsaha/gitbackup:<version> \
  -service github -backupdir /backup -use-https-clone

SSH cloning on macOS requires the same key-ownership step as Linux. Although VirtioFS handles write permissions for the backup directory automatically, git performs a strict ownership check on the SSH private key inside the container — the key file must be owned by the user running inside the container (UID 65532). Host UIDs on macOS are unrelated to container UIDs, so the ownership must be set explicitly on a copy of the key:

cp $HOME/.ssh/id_rsa /tmp/gitbackup_id_rsa
chown 65532 /tmp/gitbackup_id_rsa
chmod 600 /tmp/gitbackup_id_rsa

docker run --rm \
  -e GITHUB_TOKEN=<your-token> \
  -v $HOME/gitbackup:/backup \
  -v /tmp/gitbackup_id_rsa:/home/nonroot/.ssh/id_rsa:ro \
  -v $HOME/.ssh/known_hosts:/home/nonroot/.ssh/known_hosts:ro \
  ghcr.io/amitsaha/gitbackup:<version> \
  -service github -backupdir /backup

Windows

Docker Desktop for Windows (WSL2 backend recommended) translates volume mounts through the WSL2 VM, so no chown is needed on the host directory. Use PowerShell syntax for environment variables and paths:

# PowerShell
New-Item -ItemType Directory -Force "$env:USERPROFILE\gitbackup"

docker run --rm `
  -e GITHUB_TOKEN=$env:GITHUB_TOKEN `
  -v "${env:USERPROFILE}\gitbackup:/backup" `
  ghcr.io/amitsaha/gitbackup:<version> `
  -service github -backupdir /backup -use-https-clone

If you prefer Command Prompt:

mkdir %USERPROFILE%\gitbackup

docker run --rm ^
  -e GITHUB_TOKEN=%GITHUB_TOKEN% ^
  -v "%USERPROFILE%\gitbackup:/backup" ^
  ghcr.io/amitsaha/gitbackup:<version> ^
  -service github -backupdir /backup -use-https-clone

SSH cloning on Windows requires your SSH key to be accessible from WSL2 or Docker Desktop. The recommended approach is to store your key under WSL2 and mount it using a WSL path, or use HTTPS cloning to avoid SSH key management altogether.

Using gitbackup

gitbackup requires a GitHub API access token for backing up GitHub repositories, a GitLab personal access token for GitLab repositories, a username and API token (or app password) for Bitbucket repositories, or a [Forgejo access token][https://docs.codeberg.org/advanced/access-token/] for Forgejo.

You can supply the tokens to gitbackup using GITHUB_TOKEN, GITLAB_TOKEN, or FORGEJO_TOKEN environment variables respectively, and the Bitbucket credentials with BITBUCKET_USERNAME and either BITBUCKET_TOKEN or BITBUCKET_PASSWORD.

GitHub Specific oAuth App Flow

Starting with the 0.6 release, if you run gitbackup without specifying GITHUB_TOKEN, it will prompt you to complete a oAuth flow to grant the necessary access:

$ ./gitbackup -service github -github.repoType starred
Copy code: <some code>
then open: https://github.com/login/device

Once your authorize the app, gitbackup will retrieve the token, and also store it in your operating system's keychain/keyring (using the 99designs/keyring package - thanks!). Next time you run it, it will ask you for the keyring password and retrieve the token automatically.

OAuth Scopes/Permissions required

Bitbucket

API tokens (recommended):

• read:user:bitbucket
• read:workspace:bitbucket
• read:repository:bitbucket

App passwords (deprecated, disabled after June 9, 2026):

• Account:Read
• Repositories:Read

Note: Bitbucket has deprecated app passwords. Use API tokens instead by setting the BITBUCKET_TOKEN environment variable.

GitHub

• repo: Reading repositories, including private repositories
• user and admin:org: Basically, this gives gitbackup a lot of permissions than you may be comfortable with. However, these are required for the user migration and org migration operations.

GitLab

• api: Grants complete read/write access to the API, including all groups and projects. For some reason, read_user and read_repository is not sufficient.

Forgejo

The following permissions are required:

• read:repository
• read:user

Security and credentials

When you provide the tokens via environment variables, they remain accessible in your shell history and via