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, an Atlassian account email plus an 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_EMAIL (or BITBUCKET_USERNAME for legacy app-password setups) and either BITBUCKET_TOKEN or BITBUCKET_PASSWORD. Bitbucket additionally requires BITBUCKET_WORKSPACES (comma-separated workspace slugs) because Atlassian removed the cross-workspace listing APIs on April 14, 2026.

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 the processes' environment for the lifetime of the process. By default, SSH authentication is used to clone your repositories. If use-https-clone is specified, private repositories are cloned via https basic auth and the token provided will be stored in the repositories' .git/config.

Configuration file

Note: Migration-related flags (-github.createUserMigration, -github.listUserMigrations, etc.) are CLI-only and not supported in the config file.

Instead of passing all options as CLI flags, you can use a gitbackup.yml configuration file.

The config file is stored in the OS-specific configuration directory:

• Linux: $XDG_CONFIG_HOME/gitbackup/gitbackup.yml or ~/.config/gitbackup/gitbackup.yml
• macOS: ~/Library/Application Support/gitbackup/gitbackup.yml
• Windows: %AppData%/gitbackup/gitbackup.yml

To create a default configuration file:

```lang=bash $ gitbackup init

To create it at a custom location:

```lang=bash
$ gitbackup init --config /path/to/gitbackup.yml

This creates a gitbackup.yml with default values that you can edit:

service: github
githost_url: ""
backup_dir: ""
ignore_private: false
ignore_fork: false
use_https_clone: false
bare: false
github:
    repo_type: all
    namespace_whitelist: []
gitlab:
    project_visibility: internal
    project_membership_type: all
forgejo:
    repo_type: user

To validate your configuration file (checks field values and required environment variables):

```lang=bash $ gitbackup validate

To see available options for a subcommand:

```lang=bash
$ gitbackup init --help
$ gitbackup validate --help

The config file is automatically loaded at runtime from the default location. CLI flags override config file values, so you can use the config file for your base settings and override individual options as needed:

```lang=bash $ GITHUB_TOKEN=secret$token gitbackup -ignore-fork

To use a config file at a custom location:

```lang=bash
$ GITHUB_TOKEN=secret$token gitbackup -config /path/to/gitbackup.yml

Secrets (tokens, passwords) are not stored in the config file — they are always provided via environment variables.

Examples

Typing -help will display the command line options that gitbackup recognizes:

``` $ gitbackup -help Usage of ./gitbackup: -backupdir string Backup directory -bare Clone bare repositories -forgejo.repoType string Repo types to backup (user, starred) (default "user") -githost.url string DNS of the custom Git host -github.createUserMigration Download user data -github.createUserMigrationRetry Retry creating the GitHub user migration if we get an error (default true) -github.createUserMigrationRetryMax int Number of retries to attempt for creating GitHub user migration (default 5) -github.listUserMigrations List available user migrations -github.namespaceWhitelist string Organizations/Users from where we should clone (separate each value by a comma: 'user1,org2') -github.repoType string Repo types to backup (all, owner, member, starred) (default "all") -github.waitForUserMigration Wait for migration to complete (default true) -gitlab.projectMembershipType string Project type to clone (all, owner, member, starred) (default "all") -gitlab.projectVisibility string Visibility level of Projects to clone (internal, public, private) (default "internal") -ignore-fork Ignore repositories which are forks -ignore-private Ignore private repositories/projects -service string Git Hosted Service Name (github/gitlab/bitbucket/forgejo) -use-https-clone Use HT