{"meta":{"title":"Restoring from a backup","intro":"Restore a GitHub Enterprise Server instance using a previously created backup snapshot.","product":"Enterprise administrators","breadcrumbs":[{"href":"/en/enterprise-server@3.21/admin","title":"Enterprise administrators"},{"href":"/en/enterprise-server@3.21/admin/backing-up-and-restoring-your-instance","title":"Back up and restore"},{"href":"/en/enterprise-server@3.21/admin/backing-up-and-restoring-your-instance/restoring-from-a-backup","title":"Restore from backup"}],"documentType":"article"},"body":"# Restoring from a backup\n\nRestore a GitHub Enterprise Server instance using a previously created backup snapshot.\n\nYou 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.\n\n> \\[!WARNING] Restoring from a backup will **overwrite all existing data** on your instance. This operation cannot be undone.\n\n## Snapshot version requirements\n\nYou can only restore a snapshot if it's from at most two feature versions behind the version of the target instance.\n\nFor example:\n\n* A snapshot from version 3.17 can be restored to a target running 3.17.x, 3.18.x, or 3.19.x.\n* You cannot restore a 3.17 snapshot to 3.20 — that’s more than two versions ahead.\n\nYou 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.`\n\n## Prerequisites\n\nBefore restoring a backup:\n\n1. **Enable maintenance mode** on the target instance. See [Enabling and scheduling maintenance mode](/en/enterprise-server@3.21/admin/administering-your-instance/configuring-maintenance-mode/enabling-and-scheduling-maintenance-mode).\n2. **Verify access** to the backup storage containing the snapshot.\n3. **Pause interfering services** — if using High Availability (HA), make sure replication is stopped.\n4. **Prepare for GitHub Actions** — if enabled, ensure the target instance is configured with the correct external storage. See [Restoring with GitHub Actions enabled](/en/enterprise-server@3.21/admin/backing-up-and-restoring-your-instance/restoring-with-github-actions-enabled) for details.\n\n## Starting the restore operation\n\nTo restore from a snapshot:\n\n1. SSH into the target instance as the `admin` user.\n\n2. Run one of the following commands:\n\n   * Restore the latest snapshot:\n\n     ```shell\n     ghe-restore\n     ```\n\n   * Restore a specific snapshot. Replace `<SNAPSHOT_TIMESTAMP>` with the timestamp of the snapshot you want to restore (e.g., `YYYYMMDDTHHMMSS`).\n\n     ```shell\n     ghe-restore -s <SNAPSHOT_TIMESTAMP>\n     ```\n\n   * (Optional) Overwrite appliance configuration, certificates, and license data from the backup. The `-c` option does not control database or repository restoration:\n\n     ```shell\n     ghe-restore -c          # Latest snapshot\n     ghe-restore -s <SNAPSHOT_TIMESTAMP> -c  # Specific snapshot\n     ```\n\n3. **Finalize in Management Console:**\n\n   * Review all configuration settings (network, auth, TLS, etc.).\n   * Click **Save settings** to apply them and start services.\n   * The instance is not fully operational until this step is complete.\n\n4. **Validate the restored instance** to ensure everything works as expected.\n\n5. **If using HA**, complete the restore on a standalone instance first. Then reconfigure HA.\n\n   * If you run into sync issues (e.g., stale UUIDs in `ghe-repl-status`), run `ghe-repl-teardown`.\n   * For help, contact GitHub Support.\n\n6. **Re-register self-hosted GitHub Actions runners**, as restore invalidates previous tokens.\n\n## Snapshot rotation and retention\n\nSnapshots are automatically pruned based on your retention settings:\n\n* Only the most recent n snapshots are kept (as configured).\n* Older snapshots are deleted after each successful backup.\n* Snapshots are named using timestamps (`YYYYMMDDTHHMMSS`) for easy reference.\n* Hard links are used to store unchanged files efficiently while preserving full restore capability.\n\n## Troubleshooting restoration failures\n\nIf a restore operation fails, check:\n\n* **Backup completeness** – Make sure the snapshot wasn't interrupted or corrupted.\n* **Storage access** – Verify the instance can mount and read the backup volume.\n* **Version mismatch** – Confirm the snapshot version is compatible with the target instance.\n* **Logs** – Review `/var/log/github-backup/restore-verbose-[timestamp].log` for errors.\n\nIf the Management Console shows a generic failure, SSH into the instance to access detailed logs."}