This version of GitHub Enterprise Server will be discontinued on 2026-08-25. Discontinued releases are not supported. No patch releases will be made, even for critical security issues. For better performance, improved security, and new features in GitHub Enterprise Server, see Overview of the upgrade process. For help with the upgrade, GitHub Enterprise Support.

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.