Enterprise Server 3.17 is currently available as a release candidate.

Restoring from a backup

Restore a GitHub Enterprise Server instance using a previously created backup snapshot.

In this article

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.

Warning

Restoring from a backup will overwrite all existing data on your instance. This operation cannot be undone.

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. Enable maintenance mode on the target instance. See Enabling and scheduling maintenance mode.
  2. Verify access to the backup storage containing the snapshot.
  3. Pause interfering services — if using High Availability (HA), make sure replication is stopped.
  4. 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.

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) Force overwrite of configuration, certificates, and license data:

      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.

  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.