Overview of the upgrade process

GitHub Enterprise Server is constantly improving, with new functionality and bug fixes introduced through feature and patch releases. You are responsible for upgrades to your instance. See "About upgrades to new releases."

To upgrade an instance, you must:

Plan your upgrade strategy by choosing your upgrade version and the appropriate upgrade package, and scheduling a maintenance window.
Communicate the upgrade before and during the upgrade process.
Prepare your backup strategy by creating a backup and taking a virtual machine snapshot.
Install the upgrade package using the appropriate package and method.
Complete post-upgrade tasks.

The process you must follow to apply an upgrade package depends on how many nodes are in your deployment topology. This article provides general information for upgrading instances in a standalone or high availability configuration only.

Planning your upgrade strategy

Plan your upgrade

Review the release notes and documented known issues before performing an upgrade. See "Release notes" and "Known issues with upgrades to your instance."
Review "Upgrade requirements" to ensure you understand the requirements and recommendations for upgrading.
Check that your GitHub Enterprise Server instance's data disk is at least 15% free. GitHub recommends ensuring there is additional free storage on the disk. In some rare cases, for customers with large data volumes, this threshold may differ. See "Increasing storage capacity."
Check that you have sufficient hardware resources for GitHub Enterprise Server. 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.
Ensure you have a copy of all custom firewall rules for your GitHub Enterprise Server instance, as customized rules will not persist post-upgrade. You must reapply any custom rules following the upgrade. See "Configuring built-in firewall rules."
For instances in a high availability configuration, check that the status of replication reports OK before upgrading. See "Monitoring a high-availability configuration."
Consider configuring the IP exception list for maintenance mode, so you can temporarily limit access to your GitHub Enterprise Server instance to validate your server health after an upgrade. See "Enabling and scheduling maintenance mode."

Choose your upgrade version and package

Determine an upgrade strategy and choose a version to upgrade to.
- You can upgrade a GitHub Enterprise Server instance to a new patch release or to a new feature release.
- Refer to the Upgrade assistant to find the upgrade path from your current release version, to a new patch or feature release version.
Choose an upgrade package (hotpatch or upgrade package).
- To upgrade to a patch release, you can use a hotpatch or an upgrade package. To upgrade to a feature release, you must use an upgrade package.
- If you use an upgrade package, schedule a maintenance window for GitHub Enterprise Server end users. If you are using a hotpatch, maintenance mode is not required.
- If you have enabled automatic update checks, site administrators will be notified that an upgrade package has been downloaded and is available. See "Enabling automatic update checks".
- Release candidate builds are intended solely for use in a test environment. Do not install a release candidate build in a production environment. Do not upgrade from the release candidate to later versions, including generally available releases.

Consider if other application updates are required

Check if you need to upgrade the following applications:

GitHub Actions runners must be updated if your GitHub Enterprise Server instance uses ephemeral self-hosted runners for GitHub Actions and automatic updates are disabled. Upgrade runners to the minimum version of application required by your upgraded instance, before performing your upgrade. To find the minimum required version for your release, see "GitHub Enterprise Server releases."
GitHub Enterprise Server Backup Utilities. Your GitHub Enterprise Server Backup Utilities version needs to be the same version as, or at most two versions ahead of your GitHub Enterprise Server instance.
- You may need to upgrade GitHub Enterprise Server Backup Utilities to a newer version, prior to upgrading your instance.
- You may also want to plan to upgrade GitHub Enterprise Server Backup Utilities to a newer version after upgrading your instance.
See "Configuring backups on your instance" and the README in the GitHub Enterprise Server Backup Utilities project documentation.

Plan a maintenance window

Depending on your upgrade strategy, significant downtime may be required.
The best way to determine the expected duration of downtime is to test your upgrade in a staging environment first. See "Setting up a staging instance."
The maintenance window for your upgrade depends on the type of upgrade you perform.
- Upgrades using a hotpatch usually don't require a maintenance window. Sometimes a reboot is required, which you can perform at a later time.
  
  Note
  
  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."
- Patch releases using an upgrade package typically require less than five minutes of downtime.
- Upgrading to a new feature release that include data migrations may cause a few hours of downtime, depending on storage performance and the amount of data that is migrated. During this time none of your users will be able to use the enterprise.

Communicating your upgrade

Prior to your upgrade, you can publish a global announcement banner to highlight important information to your users, such as incoming changes or possible downtime. See "Customizing user messages for your enterprise."
At the time of the upgrade, you can enable maintenance mode and set a custom message to inform users that the instance is temporarily unavailable. See "Enabling and scheduling maintenance mode."

Preparing your backup strategy

Create a backup snapshot

Ensure you have a recent, successful backup snapshot of your instance's primary node before you start the upgrade process. See "Configuring backups on your instance" and the README in the GitHub Enterprise Server Backup Utilities project documentation.

Check the status of background jobs, and review the upgrade log for errors.
Check basic GitHub Enterprise Server functionality. For example, ensure you can sign in via the user interface, and verify that several of your organizations, repositories and issues can be reached as expected. It's also a good idea to manually run several Git fetches, clones, and pushes using SSH and/or HTTPS, and check that API requests and webhook deliveries complete successfully.
Reapply any custom firewall rules. See "Configuring built-in firewall rules."
Delete any VM snapshots taken prior to upgrading. See "Taking a snapshot."
Disable maintenance mode, and update any pre-upgrade communications such as announcement banners. See "Customizing user messages for your enterprise" and "Enabling and scheduling maintenance mode."
Monitor all queued background jobs on your instance to ensure they complete successfully. See "Command-line utilities."

Overview of the upgrade process

In this article