Upgrade requirements

Recommendations

• Include as few upgrades as possible in your upgrade process. For example, instead of upgrading from GitHub Enterprise 3.13 to 3.14 to 3.15, you could upgrade from GitHub Enterprise 3.13 to 3.15. Use the Upgrade assistant to find the upgrade path from your current release version.
• If you’re several versions behind, upgrade your GitHub Enterprise Server instance as far forward as possible with each step of your upgrade process. Using the latest version possible on each upgrade allows you to take advantage of performance improvements and bug fixes. For example, you could upgrade from GitHub Enterprise 2.7 to 2.8 to 2.10, but upgrading from GitHub Enterprise 2.7 to 2.9 to 2.10 uses a later version in the second step.
• Use the latest patch release when upgrading. Browse to the GitHub Enterprise Server Releases page. Next to the release you are upgrading to, click Download, then click the Upgrading tab.
• Use a staging instance to test the upgrade steps. For more information, see Setting up a staging instance.
• When running multiple upgrades, ensure data migrations and upgrade tasks running in the background are fully complete before proceeding to the next feature upgrade. To check the status of these processes, you can use the ghe-migrations and ghe-check-background-upgrade-jobs command-line utilities. To use ghe-check-background-upgrade-jobs with GitHub Enterprise Server 3.11, your instance must run version 3.11.1 or later. For more information, see Command-line utilities.
• Take a snapshot before upgrading your virtual machine. For more information, see Taking a snapshot.
• Ensure you have a recent, successful backup of your instance. For more information, see the GitHub Enterprise Server Backup Utilities README.md file.

Requirements

• You must upgrade from a feature release that's at most two releases behind. For example, to upgrade to GitHub Enterprise 3.15, you must be on GitHub Enterprise 3.14 or 3.13.
• When upgrading using an upgrade package, schedule a maintenance window for GitHub Enterprise Server end users.
• You can upgrade GitHub Enterprise Server to the latest patch release using a hotpatch.

You can use hotpatching to upgrade to a newer patch release, but not a feature release. For example, you can upgrade from 2.10.1 to 2.10.5 because they are in the same feature series, but not from 2.10.9 to 2.11.0 because they are in a different feature series.

Hotpatches do not always require a reboot. When you install the hotpatch, you'll see a message in the terminal if any of the packages need a reboot to complete the update. You can schedule this reboot at a convenient time but we recommend rebooting as soon as practical, especially if there are any security fixes.

Hotpatches require a configuration run, which can cause a brief period of errors or unresponsiveness for some or all services on your GitHub Enterprise Server instance. You are not required to enable maintenance mode during installation of a hotpatch, but doing so will guarantee that users see a maintenance page instead of errors or timeouts. See Enabling and scheduling maintenance mode.

• A hotpatch may require downtime if the affected services (like kernel, MySQL, or Elasticsearch) require a VM reboot or a service restart. You'll be notified when a reboot or restart is required. You can complete the reboot or restart at a later time.
• Additional root storage must be available when upgrading through hotpatching, as it installs multiple versions of certain services until the upgrade is complete. Pre-flight checks will notify you if you don't have enough root disk storage.
• When upgrading through hotpatching, your instance cannot be too heavily loaded, as it may impact the hotpatching process.
• Upgrading to GitHub Enterprise Server 2.17 migrates your audit logs from Elasticsearch to MySQL. This migration also increases the amount of time and disk space it takes to restore a snapshot. Before migrating, check the number of bytes in your Elasticsearch audit log indices with this command:

curl -s http://localhost:9201/audit_log/_stats/store | jq ._all.primaries.store.size_in_bytes

Use the number to estimate the amount of disk space the MySQL audit logs will need. The script also monitors your free disk space while the import is in progress. Monitoring this number is especially useful if your free disk space is close to the amount of disk space necessary for migration.

When upgrading, pre-flight checks evaluate if the minimum requirements for system hardware resources, such as memory, CPU cores, and user and root disk storage, are available to your instance. If pre-flight checks determine there are insufficient resources, or otherwise fail, you are notified and the upgrade is aborted.

Next steps

After reviewing these recommendations and requirements, you can upgrade GitHub Enterprise Server. For more information, see Overview of the upgrade process.