This version of GitHub Enterprise Server was discontinued on 2024-03-26. No patch releases will be made, even for critical security issues. For better performance, improved security, and new features, upgrade to the latest version of GitHub Enterprise Server. For help with the upgrade, contact GitHub Enterprise support.

Known issues with backups for your instance

See an overview of workarounds for issues that impact the backup or restoration process for GitHub Enterprise Server.

In this article

About known issues with GitHub Enterprise Server backups

GitHub provides workarounds for the following issues that could impact backup or restoration of data for a GitHub Enterprise Server instance. For more information, see "Known issues" in the GitHub Enterprise Server release notes.

Users cannot sign in after restoration of a backup

Note: This known issue has been fixed in GitHub Enterprise Server Backup Utilities 3.8.1.

If you used GitHub Enterprise Server Backup Utilities 3.7.0 or 3.8.0 to back up an instance running any release in the GitHub Enterprise Server 3.7 or 3.8 series, after you restore the backup to a new instance, users cannot sign in. Though users cannot sign in, the backup itself is unaffected and all data is intact.

After you restore an existing backup affected by this issue, you can resolve the issue by modifying the configuration on the new instance.

Restoring from an existing backup

If you've restored an existing backup from GitHub Enterprise Server Backup Utilities 3.8.0 to a new instance and users cannot sign in, you must output configuration data from the source GitHub Enterprise Server instance and adjust the configuration on the target instance.

To ensure users can sign into the new target instance, ensure that your environment meets the following requirements.

  1. SSH into the source GitHub Enterprise Server instance that you backed up. If your instance comprises multiple nodes, for example if high availability or geo-replication are configured, SSH into the primary node. If you use a cluster, you can SSH into any node. Replace HOSTNAME with the actual hostname of your instance. For more information about SSH access, see "Accessing the administrative shell (SSH)."

    Shell
    ssh -p 122 admin@HOSTNAME

  2. To display a list of decryption keys, run the following command.

    Shell
    ghe-config secrets.github.encrypted-column-keying-material

  3. Copy the output to a safe and temporary location.

  4. To display a list of encryption keys, run the following command.

    Shell
    ghe-config secrets.github.encrypted-column-current-encryption-key

  5. Copy the output to a safe and temporary location.

  6. SSH into the destination GitHub Enterprise Server instance where you restored the backup. Replace HOSTNAME with the actual hostname of your instance.

    Shell
    ssh -p 122 admin@HOSTNAME

  7. Enable maintenance mode. For more information, see "Enabling and scheduling maintenance mode."

  8. To verify that the destination instance is ready for configuration, run the following commands. There should be no output displayed.

    Shell
    ghe-config secrets.github.encrypted-column-keying-material
ghe-config secrets.github.encrypted-column-current-encryption-key

  9. To update the decryption keys on the destination instance, run the following command. Replace DECRYPTION-KEY-LIST with the output from step 1.

    Shell
    ghe-config secrets.github.encrypted-column-keying-material "DECRYPTION-KEY-LIST"

  10. To update the encryption key on the destination instance, run the following command. Replace ENCRYPTION-KEY with the output from step 4.

    Shell
    ghe-config secrets.github.encrypted-column-current-encryption-key "ENCRYPTION-KEY"

  11. To apply the configuration, run the following command.

    Shell
    ghe-config-apply

  12. Wait for the configuration run to complete.

  13. To ensure that the target instance's configuration contains the keys, run the following commands and verify that the output matches step 1 and step 4.

    Shell
    ghe-config secrets.github.encrypted-column-keying-material
ghe-config secrets.github.encrypted-column-current-encryption-key

  14. Have a user sign into the destination instance. If any issues arise, contact GitHub Enterprise Support. For more information, see "Contacting GitHub Support."