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:

1. Plan your upgrade strategy by choosing your upgrade version and the appropriate upgrade package, and scheduling a maintenance window.
2. Communicate the upgrade before and during the upgrade process.
3. Prepare your backup strategy by creating a backup and taking a virtual machine snapshot.
4. Install the upgrade package using the appropriate package and method.
5. 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.

Create a VM snapshot

If you're upgrading to a new feature release, a virtual machine (VM) snapshot is required. If you're upgrading to a patch release, you can attach the existing data disk.

Create a virtual machine (VM) snapshot of your instance's primary node immediately before upgrading, and only when maintenance mode has been enabled or the instance has been powered down. See Taking a snapshot.

Installing an upgrade package

Review the considerations for upgrades, and complete any preparation steps as described above, before you start installing an upgrade package.

The instructions for upgrading your GitHub Enterprise Server instance differ depending on the type of upgrade you're performing and the number of nodes your instance has.

• Upgrading with a hotpatch
  • Upgrading a standalone instance using a hotpatch
  • Upgrading an instance with multiple nodes using a hotpatch
• Upgrading with an upgrade package
  • Upgrading a standalone instance using an upgrade package
  • Upgrading an instance with multiple nodes using an upgrade package

Completing post-upgrade tasks

• 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.