Restoring from a backup

You can restore a GitHub Enterprise Server instance from a backup using the command line. The backup service supports full instance restoration, including configuration and user data.

Snapshot version requirements

You can only restore a snapshot if it's from at most two feature versions behind the version of the target instance.

For example:

• A snapshot from version 3.17 can be restored to a target running 3.17.x, 3.18.x, or 3.19.x.
• You cannot restore a 3.17 snapshot to 3.20 — that’s more than two versions ahead.

You also can’t restore from a newer version to an older one. For example, trying to restore a 3.18 snapshot to a 3.17 instance will fail with: Error: Snapshot can not be restored to an older release of GitHub Enterprise Server.

Prerequisites

Before restoring a backup:

1. Provision a new GitHub Enterprise Server instance to use as a target for the restoration of your backup. For more information, see Setting up a GitHub Enterprise Server instance.
2. Tear down replication. If using High Availability (HA), run ghe-repl-teardown on the target instance. Stopping replication with ghe-repl-stop is not sufficient, because the target remains configured as part of a replication pair and the restore fails. See Removing a high availability replica.
3. Prepare for GitHub Actions: if enabled, ensure the target instance is configured with the correct external storage. See Restoring with GitHub Actions enabled for details.
4. Enable maintenance mode on the target instance. See Enabling and scheduling maintenance mode.
5. Verify access to the backup storage containing the snapshot after attaching and mounting the backup disk volume to the target instance. See Configuring the backup service.

Starting the restore operation

To restore from a snapshot:

1. SSH into the target instance as the admin user.

2. Run one of the following commands:

   • Restore the latest snapshot:

     ghe-restore
     

   • Restore a specific snapshot. Replace <SNAPSHOT_TIMESTAMP> with the timestamp of the snapshot you want to restore (e.g., YYYYMMDDTHHMMSS).

     ghe-restore -s <SNAPSHOT_TIMESTAMP>
     

   • (Optional) Overwrite appliance configuration, certificates, and license data from the backup. The -c option does not control database or repository restoration:

     ghe-restore -c # Latest snapshot
     ghe-restore -s <SNAPSHOT_TIMESTAMP> -c # Specific snapshot
     

3. Finalize in Management Console:

   • Review all configuration settings (network, auth, TLS, etc.).
   • Click Save settings to apply them and start services.
   • The instance is not fully operational until this step is complete.

4. Validate the restored instance to ensure everything works as expected.

   • (Optional) Configure an IP exception list on the restored instance to allow access to a specified list of IP addresses. For more information, see Enabling and scheduling maintenance mode.

5. If using HA, complete the restore on a standalone instance first. Then reconfigure HA.

   • If you run into sync issues (e.g., stale UUIDs in ghe-repl-status), run ghe-repl-teardown.
   • For help, contact GitHub Support.

6. Re-register self-hosted GitHub Actions runners, as restore invalidates previous tokens.

Snapshot rotation and retention

Snapshots are automatically pruned based on your retention settings:

• Only the most recent n snapshots are kept (as configured).
• Older snapshots are deleted after each successful backup.
• Snapshots are named using timestamps (YYYYMMDDTHHMMSS) for easy reference.
• Hard links are used to store unchanged files efficiently while preserving full restore capability.

Troubleshooting restoration failures

If a restore operation fails, check:

• Backup completeness – Make sure the snapshot wasn't interrupted or corrupted.
• Storage access – Verify the instance can mount and read the backup volume.
• Version mismatch – Confirm the snapshot version is compatible with the target instance.
• Logs – Review /var/log/github-backup/restore-verbose-[timestamp].log for errors.

If the Management Console shows a generic failure, SSH into the instance to access detailed logs.