In this guide

• Upgrading strategy
• Preparing to upgrade
• Taking a snapshot
• Upgrading a single appliance
• Upgrading a High Availability pair
• Restoring from a failed upgrade

Upgrading strategy

Recommendations

• Upgrade in as few steps as possible. For example you could upgrade from GitHub Enterprise 2.7 to 2.8 to 2.9, but upgrading from GitHub Enterprise 2.7 to 2.9 is simpler and faster.
• Upgrade to later versions sooner rather than later. 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.6 to 2.7 to 2.9, but upgrading from GitHub Enterprise 2.6 to 2.8 to 2.9 uses a later version in the second step.
• Use the latest patch release when upgrading. Upgrade packages are available from:
  • GitHub Enterprise Download Page for currently supported versions.
  • Upgrade packages for older releases that are no longer supported.
• When running multiple upgrades, we recommend waiting at least 24 hours between feature upgrades to allow data migrations and backgrounded upgrade tasks 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 2.9, you must be on GitHub Enterprise 2.8 or 2.7. You can't upgrade from 2.6 to 2.9, because that's three releases behind.

Preparing to upgrade

1. Create a fresh backup of your primary instance with the GitHub Enterprise Backup Utilities.
2. Plan to take a snapshot of your existing data immediately after placing the instance in maintenance mode.
3. Schedule a maintenance window for end users of your GitHub Enterprise instance. Patch releases (e.g. 2.0.1 to 2.0.2) typically require less than five minutes of downtime. However, feature releases (e.g. 2.0.2 to 2.1.0) that include data migrations will take longer depending on storage performance and the amount of data. For more information, see maintenance mode.

Taking a snapshot

A snapshot is a checkpoint of a virtual machine at a point in time. We highly recommend taking a snapshot prior to upgrading your virtual machine. If an upgrade fails, you should revert back to a snapshot to restore the state of your VM prior to the upgrade, because irreversible database migrations may have run during the failed upgrade.

There are two types of snapshots:

• A VM snapshot, which saves your entire VM state, including user data and configuration data.
• A data disk snapshot, which saves only your user data.

Taking a snapshot of your entire VM can be a time-consuming operation and requires a significant amount of disk space. For the upgrade process, we recommend taking a snapshot of just your data disk. Note that some platforms don't allow you to take a snapshot of just your data disk, requiring you to take a snapshot of the entire VM.

Platform	Snapshot method	Snapshot documentation URL
Amazon AWS	Disk	https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ebs-creating-snapshot.html
Azure	VM	https://azure.microsoft.com/en-us/documentation/articles/backup-azure-vms/
Hyper-V	VM	https://technet.microsoft.com/en-us/library/dd851843.aspx
VMware	VM	https://pubs.vmware.com/vsphere-50/index.jsp#com.vmware.vsphere.vm_admin.doc_50/GUID-9720B104-9875-4C2C-A878-F1C351A4F3D8.html
XenServer	VM	http://docs.citrix.com/en-us/xencenter/6-2/xs-xc-vms-snapshots.html

Upgrading a single appliance

1. As a site admin, SSH into your GitHub Enterprise instance:

   ssh -p 122 admin@hostname
   

2. Copy the URL for the upgrade package (.pkg file) to the clipboard from:

   • GitHub Enterprise Download Page for currently supported versions.
   • Upgrade packages for older releases that are no longer supported.

3. Download the upgrade package to your GitHub Enterprise instance using curl:

   admin@hostname:~$ curl -L -O UPGRADE-PKG-URL
   

4. Enable maintenance mode and wait for all active processes to complete on the GitHub Enterprise instance.

5. Run the ghe-upgrade command, providing the package file name downloaded in the previous step:

   admin@hostname:~$ ghe-upgrade GITHUB-UPGRADE.pkg
   *** verifying upgrade package signature...
   

   After the package signature is verified, information on the current and target root partition is displayed and you will be prompted to confirm whether to continue with the upgrade and restart:

   *** applying update...
   This package will upgrade your installation to version version-number
   Current root partition: /dev/xvda1 [version-number]
   Target root partition:  /dev/xvda2
   Proceed with installation? [y/N]
   

   Once you've accepted the upgrade details, the new root filesystem is written to the secondary partition and the instance is automatically restarted:

   *** extracting new root filesystem...
   676MB 0:01:04 [10.5MB/s] [=============================================================================>] 100%
   *** setting up bootloader configuration...
   *** Rebooting!
   Broadcast message from admin@hostname
   (/dev/pts/3) at 20:11 ...
   The system is going down for reboot NOW!
   Connection to hostname closed.
   

6. The instance will reboot in maintenance mode. Disable maintenance mode to make it accessible to your users again.

Upgrading a High Availability pair

Upgrading the primary instance

1. On the primary instance, enable maintenance mode and wait for all active processes to finish.

2. Connect to the replica instance over SSH as the "admin" user on port 122:

   ssh -p 122 admin@replica-host
   

3. On the replica instance, run ghe-repl-stop to stop replication.

4. On the primary instance, use the procedure for a single appliance. You can skip step 4 since the primary instance is already in maintenance mode.

Upgrading the replica instance

1. On the replica instance, follow the procedure for a single appliance. There is no need to enable maintenance mode and save the settings after upgrading.

2. After the replica instance reboots, connect to it over SSH on port 122 as the "admin" user.

   ssh -p 122 admin@replica-host
   

3. Verify the upgrade by running:

   cat /etc/github/enterprise-release
   

   RELEASE_VERSION should reflect the version you have upgraded to.

4. On the replica instance, replication will automatically start. To ensure all replication services are running appropriately, run ghe-repl-status. This command will return OK for all services when a successful replication is in progress.

   Note: While the resync is in progress ghe-repl-status may return messages indicating that replication is behind. For example: CRITICAL: git replica is lagging 1481.744s behind primary. These are expected.

   If the command returns Replication is not running, the replication may still be starting. Wait about one minute before running ghe-repl-status again.

   If replication started correctly, the replica is successfully upgraded and you're finished. Otherwise, continue with the next steps to manually start the replication.

5. On the replica instance, run ghe-repl-setup <primary-instance-ip> again.

6. On the replica instance, to begin replication, run ghe-repl-start.
7. On the replica instance, to ensure all replication services are running appropriately, run ghe-repl-status. This command will return OK for all services when successful replication is in progress.

Restoring from a failed upgrade

If an upgrade fails or is interrupted, you should revert your instance back to its previous state. The process for completing this depends on whether you're using a VM snapshot or a data disk snapshot.

Using a data disk snapshot

1. Enable maintenance mode and wait for all active processes to complete on the GitHub Enterprise instance.
2. To restore your boot partition, run ghe-rollback-rootfs. This command restores only the boot partition and will turn the VM off when it's finished.
3. To restore your data partition, revert to your previous user data snapshot.
4. After the restoration finishes, start your VM.

Using a VM snapshot

If you created a whole VM snapshot, refer to the instructions for your platform to restore your VM snapshot.