Skip to content

Installation

Jump to bottom
Csaba Polyak edited this page Sep 28, 2026 · 1 revision

Installation

GitHub Mirror Backup is designed to run on Linux servers, NAS systems and other always-on machines.

The installation consists of four basic steps:

  1. Install the required tools

  2. Copy the script

  3. Configure GitHub authentication

  4. Run the first backup

Requirements

The following commands must be available:

bash
git
curl
jq
ssh

The script requires Bash 4.4 or newer because it uses associative arrays.

Check the installed versions:

bash --version
git --version
curl --version
jq --version
ssh -V

Install dependencies

On Debian/Ubuntu:

sudo apt update
sudo apt install git curl jq openssh-client

On Arch Linux:

sudo pacman -S git curl jq openssh

On other Linux distributions, install the equivalent packages using the distribution's package manager.

On NAS systems, some of these packages may already be installed or provided by the NAS package manager.

Download the script

Clone the project:

git clone https://github.com/USERNAME/github-mirror-backup.git
cd github-mirror-backup

Alternatively, download github-backup.sh directly from the repository.

Make it executable:

chmod +x github-backup.sh

Configure the backup destination

Open the script:

nano github-backup.sh

Find:

BASE="/volume1/Archivum"

Change it to the desired backup location.

For example:

BASE="/srv/backups/github"

The destination must be writable by the user running the script.

The script automatically creates the _logs directory.

Configure GitHub authentication

Follow the instructions in:

GitHub Authentication

You need both:

  • a GitHub Personal Access Token for repository discovery

  • an SSH key with access to the repositories

The token should be stored at:

~/.config/github/token

Verify SSH

Before running the backup, test GitHub SSH authentication:

ssh -T git@github.com

A successful authentication should look similar to:

Hi USERNAME! You've successfully authenticated, but GitHub does not provide shell access.

If this fails, fix SSH authentication before continuing.

Verify the token

Make sure the token file exists:

ls -l ~/.config/github/token

Recommended permissions:

chmod 600 ~/.config/github/token

Run the first backup

Start the script manually:

./github-backup.sh

The script will:

SYSTEM CHECK
     ↓
GITHUB API
     ↓
GITHUB SSH
     ↓
REPOSITORY DISCOVERY
     ↓
MIRRORING
     ↓
SUMMARY

The first run may take significantly longer than later runs because every repository has to be mirrored for the first time.

For a large GitHub account, this can generate considerable disk, network and CPU activity.

Expected output

A successful run ends with:

✓ COMPLETED SUCCESSFULLY

If some repositories could not be backed up:

✗ COMPLETED WITH 1 ERROR(S)

The script continues processing other repositories when an individual repository fails.

The exit code can be checked with:

echo $?

Possible values:

Code | Meaning -- | -- 0 | Everything completed successfully 1 | Backup completed with repository errors 2 | Fatal error

Check the backup

After the first run:

ls -lah "$BASE"

A mirror should look like:

project-a.git/
project-b.git/
project-c.git/

These are bare Git repositories. They intentionally do not contain a normal working directory.

To inspect a mirror:

git --git-dir=/path/to/project.git show-ref

You can also verify that Git recognizes it as a bare repository:

git --git-dir=/path/to/project.git rev-parse --is-bare-repository

Expected result:

true

Running on a NAS

The script does not require a special NAS integration.

The important requirements are:

  • the backup directory is mounted and writable

  • Git, curl, jq and SSH are available

  • the user running the task has access to the SSH key

  • the token file is available in that user's home directory

For Synology DSM, the script can be executed through Task Scheduler after the manual first run has been verified.

See:

Scheduling

File layout

A typical installation may look like:

~/github-mirror-backup/
└── github-backup.sh

~/.config/github/
└── token


~/.ssh/
├── id_ed25519
└── id_ed25519.pub


/backup/github/
├── repository-a.git/
├── repository-b.git/
└── _logs/
└── github-backup-YYYY-MM-DD_HH-MM-SS.log

The script itself does not need to be located inside the backup directory.

Keeping the script separate from the backup data makes upgrades and repository management easier.

Updating the script

If the project was installed using Git:

cd github-mirror-backup
git pull

Review any configuration changes before running the updated version.

The backup repositories themselves are not modified by updating the script.

First-run checklist

Before scheduling the backup, verify:

  • Required commands are installed

  • GitHub API token exists

  • Token permissions are sufficient

  • SSH authentication works

  • Backup destination is writable

  • Script is executable

  • First manual backup completed

  • Failed repositories, if any, have been investigated

  • Backup directory contains the expected mirrors

  • Logs are being created

Once the manual backup works correctly, the script is ready to be scheduled.

# Installation

GitHub Mirror Backup is designed to run on Linux servers, NAS systems and other always-on machines.

The installation consists of four basic steps:

  1. Install the required tools
  2. Copy the script
  3. Configure GitHub authentication
  4. Run the first backup

Requirements

The following commands must be available:

bash
git
curl
jq
ssh

The script requires Bash 4.4 or newer because it uses associative arrays.

Check the installed versions:

bash --version
git --version
curl --version
jq --version
ssh -V

Install dependencies

On Debian/Ubuntu:

sudo apt update
sudo apt install git curl jq openssh-client

On Arch Linux:

sudo pacman -S git curl jq openssh

On other Linux distributions, install the equivalent packages using the distribution's package manager.

On NAS systems, some of these packages may already be installed or provided by the NAS package manager.

Download the script

Clone the project:

git clone https://github.com/USERNAME/github-mirror-backup.git
cd github-mirror-backup

Alternatively, download github-backup.sh directly from the repository.

Make it executable:

chmod +x github-backup.sh

Configure the backup destination

Open the script:

nano github-backup.sh

Find:

BASE="/volume1/Archivum"

Change it to the desired backup location.

For example:

BASE="/srv/backups/github"

The destination must be writable by the user running the script.

The script automatically creates the _logs directory.

Configure GitHub authentication

Follow the instructions in:

[GitHub Authentication](GitHub-Authentication)

You need both:

  • a GitHub Personal Access Token for repository discovery
  • an SSH key with access to the repositories

The token should be stored at:

~/.config/github/token

Verify SSH

Before running the backup, test GitHub SSH authentication:

ssh -T git@github.com

A successful authentication should look similar to:

Hi USERNAME! You've successfully authenticated, but GitHub does not provide shell access.

If this fails, fix SSH authentication before continuing.

Verify the token

Make sure the token file exists:

ls -l ~/.config/github/token

Recommended permissions:

chmod 600 ~/.config/github/token

Run the first backup

Start the script manually:

./github-backup.sh

The script will:

SYSTEM CHECK
     ↓
GITHUB API
     ↓
GITHUB SSH
     ↓
REPOSITORY DISCOVERY
     ↓
MIRRORING
     ↓
SUMMARY

The first run may take significantly longer than later runs because every repository has to be mirrored for the first time.

For a large GitHub account, this can generate considerable disk, network and CPU activity.

Expected output

A successful run ends with:

✓ COMPLETED SUCCESSFULLY

If some repositories could not be backed up:

✗ COMPLETED WITH 1 ERROR(S)

The script continues processing other repositories when an individual repository fails.

The exit code can be checked with:

echo $?

Possible values:

Code Meaning
0 Everything completed successfully
1 Backup completed with repository errors
2 Fatal error

Check the backup

After the first run:

ls -lah "$BASE"

A mirror should look like:

project-a.git/
project-b.git/
project-c.git/

These are bare Git repositories. They intentionally do not contain a normal working directory.

To inspect a mirror:

git --git-dir=/path/to/project.git show-ref

You can also verify that Git recognizes it as a bare repository:

git --git-dir=/path/to/project.git rev-parse --is-bare-repository

Expected result:

true

Running on a NAS

The script does not require a special NAS integration.

The important requirements are:

  • the backup directory is mounted and writable
  • Git, curl, jq and SSH are available
  • the user running the task has access to the SSH key
  • the token file is available in that user's home directory

For Synology DSM, the script can be executed through Task Scheduler after the manual first run has been verified.

See:

[Scheduling](Scheduling)

File layout

A typical installation may look like:

~/github-mirror-backup/
└── github-backup.sh

~/.config/github/
└── token

~/.ssh/
├── id_ed25519
└── id_ed25519.pub

/backup/github/
├── repository-a.git/
├── repository-b.git/
└── _logs/
    └── github-backup-YYYY-MM-DD_HH-MM-SS.log

The script itself does not need to be located inside the backup directory.

Keeping the script separate from the backup data makes upgrades and repository management easier.

Updating the script

If the project was installed using Git:

cd github-mirror-backup
git pull

Review any configuration changes before running the updated version.

The backup repositories themselves are not modified by updating the script.

First-run checklist

Before scheduling the backup, verify:

  • Required commands are installed
  • GitHub API token exists
  • Token permissions are sufficient
  • SSH authentication works
  • Backup destination is writable
  • Script is executable
  • First manual backup completed
  • Failed repositories, if any, have been investigated
  • Backup directory contains the expected mirrors
  • Logs are being created

Once the manual backup works correctly, the script is ready to be scheduled.

Clone this wiki locally