Upgrade requirements

Recommendations

• Include as few upgrades as possible in your upgrade process. For example, instead of upgrading from GitHub Enterprise 2.22 to 3.0 to 3.1, you could upgrade from GitHub Enterprise 2.22 to 3.1.
• 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, wait at least 24 hours between feature upgrades to allow data migrations and upgrade tasks running in the background to fully complete.

Requirements

• You must upgrade from a feature release that's at most two releases behind. For example, to upgrade to GitHub Enterprise 3.1, you must be on GitHub Enterprise 3.0 or 2.22.
• You can upgrade GitHub Enterprise Server to the latest patch release using a hotpatch, which does not require a maintenance window and usually does not require a reboot. 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.
• 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. Pre-flight checks will consider the load average and the upgrade will fail if the load average is too high.- 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.

About minimum requirements for GitHub Enterprise Server 3.0 and later

Before upgrading to GitHub Enterprise Server 3.0 or later, review the hardware resources you've provisioned for your instance. GitHub Enterprise Server 3.0 introduces new features such as GitHub Actions and GitHub Packages, and requires more resources than versions 2.22 and earlier. For more information, see the GitHub Enterprise Server 3.0 release notes.

Increased requirements for GitHub Enterprise Server 3.0 and later are bold in the following table.

User licenses	vCPUs	Memory	Attached storage	Root storage
Trial, demo, or 10 light users	4 Up from 2	32 GB Up from 16 GB	150 GB Up from 100 GB	200 GB
10 to 3,000	8 Up from 4	48 GB Up from 32 GB	300 GB Up from 250 GB	200 GB
3,000 to 5000	12 Up from 8	64 GB	500 GB	200 GB
5,000 to 8000	16 Up from 12	96 GB	750 GB	200 GB
8,000 to 10,000+	20 Up from 16	160 GB Up from 128 GB	1000 GB	200 GB

For more information about adjusting resources for an existing instance, see "Increasing storage capacity" and "Increasing CPU or memory resources."

Next steps

After reviewing these recommendations and requirements, you can upgrade GitHub Enterprise Server. For more information, see "Upgrading GitHub Enterprise Server."