We recommend that you install the GitHub Enterprise Backup Utilities on a dedicated server to back up and restore your appliance, but you can still use the existing command-line utilities if you prefer.

For more information, see "Backing up GitHub Enterprise."

Warning: We recommend that Windows users run our backup scripts on Cygwin. Other SSH options may result in corrupt backup files on that platform.

  1. Add an SSH key for shell access to your appliance.

  2. Enable maintenance mode on your appliance and wait for all of the active processes to complete. It is particularly important to wait for all Git operations to complete because they could cause your repositories to be backed up in an inconsistent state.

  3. Back up all Git repository data.

  4. Run ghe-export-pages to back up generated GitHub Pages sites.

    ssh admin@hostname -- 'ghe-export-pages' > ghe-pages-backup.tar

  5. Run ghe-export-mysql to back up MySQL data. This includes user accounts, commit comments, pull requests, and issues.

    ssh admin@hostname -- 'ghe-export-mysql' | gzip > ghe-mysql-backup.sql.gz

  6. Run ghe-export-redis to back up Redis data. This includes a variety of cached data counts and other settings required by the application.

    ssh admin@hostname -- 'ghe-export-redis' > ghe-redis-backup.rdb

  7. Run ghe-export-authorized-keys to back up installed SSH authorized keys for the admin SSH user. When you import these keys on another Enterprise appliance, they will allow you to continue to SSH into that appliance with the same keys that you are using now.

    ssh admin@hostname -- 'ghe-export-authorized-keys' > ghe-authorized-keys-backup.json

  8. Run ghe-export-ssh-host-keys to back up the SSH host keys. When you import these keys on another Enterprise appliance, they will prevent SSH fingerprint mismatch warnings.

    ssh admin@hostname -- 'ghe-export-ssh-host-keys' > ghe-ssh-host-keys-backup.tar

  9. Optionally run ghe-export-es-indices to back up ElasticSearch indexes for repositories, code, users, and audit log data. You don't have to—these can be recreated automatically, but that process takes some time.

    ssh admin@hostname -- 'ghe-export-es-indices' > ghe-es-indices-backup.tar

  10. Disable maintenance mode on your appliance.

Troubleshooting

In rare cases, the backup scripts may fail with an error message containing the phrase file changed as we read it. For example:

tar: repositories/username/repo-name/objects/pack: file changed as we read it

This will only happen if data is modified while the backup script is accessing it (e.g. when users push changes to a repository that is being backed up). To prevent this from happening, you should always enable maintenance mode before you back up your data.