In this guide

• Preparing to upgrade
• Taking a snapshot
• Upgrading with an upgrade package
• Restoring from a failed upgrade

Preparing to upgrade

1. Determine an upgrade strategy. For more information, see "About upgrade requirements."
2. Create a fresh backup of your primary instance with the GitHub Enterprise GitHub Enterprise Backup Utilities. For more information, see the GitHub Enterprise Backup Utilities README.md file.

3. Schedule a maintenance window for GitHub Enterprise end users.

   Note: The maintenance window is dependent on the upgrade type you perform. Following the versioning scheme of MAJOR.FEATURE.PATCH, patch releases using an upgrade package typically require less than five minutes of downtime. Feature releases that include data migrations take longer depending on storage performance and the amount of data that's migrated. For more information, see "Enabling and scheduling maintenance mode."

4. Run a migration script before completing the upgrade if you're upgrading to GitHub Enterprise 2.11 or later from either 2.9 or 2.10. For more information, see "Migrating audit logs to GitHub Enterprise 2.11 or later."
   

Taking a snapshot

A snapshot is a checkpoint of a virtual machine (VM) at a point in time. We highly recommend taking a snapshot before upgrading your virtual machine so that if an upgrade fails, you can revert your VM back to the snapshot.

There are two types of snapshots:

• VM snapshots save your entire VM state, including user data and configuration data. This snapshot method requires a large amount of disk space and is time consuming.

• Data disk snapshots only save your user data.We recommend using this snapshot method for the upgrade process.

  Notes:

  • Some platforms don't allow you to take a snapshot of just your data disk. For these platforms, you'll need to take a snapshot of the entire VM.
  • If your hypervisor does not support full VM snapshots, you should take a snapshot of the root disk and data disk in quick succession.

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 with an upgrade package

Use an upgrade package to upgrade to the latest release. For more information, see "About upgrade requirements."

Upgrading a single appliance with an upgrade package

1. SSH into your GitHub Enterprise instance:

   ssh -p 122 admin@hostname
   

2. Browse to the GitHub Enterprise Releases page, on the right side next to the release you are upgrading to, click Download, then click the Upgrading tab. Select the appropriate platform and copy the URL for the upgrade package (.pkg file).

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. For more information, see "Enabling and scheduling maintenance mode."

   Note: When upgrading the primary appliance in a High Availability configuration, the appliance should already be in maintenance mode if you are following the instructions in Upgrading the primary instance.

5. Run the ghe-upgrade command using the package file name:

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

6. Confirm that you'd like to continue with the upgrade and restart after the package signature verifies. The new root filesystem writes to the secondary partition and the instance automatically restarts in maintenance mode:

   *** 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]
   

7. For single appliance upgrades, disable maintenance mode so users can use your GitHub Enterprise instance.

   Note: When upgrading appliances in a High Availability configuration you should remain in maintenance mode until you have upgraded all of the replicas and replication is current. For more information, see Upgrading a replica instance.

Upgrading an appliance that has replica instances using an upgrade package

Appliances configured for high-availability use replica instances in addition to primary instances. To upgrade these appliances, you'll need to upgrade both the primary instance and the replica instance, one at a time.

Upgrading the primary instance

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

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. Upgrade the primary instance. For more information, see the procedure for upgrading a single appliance with an upgrade package.

Upgrading a replica instance

1. Upgrade the replica instance. For more information, see the procedure for upgrading a single appliance with an upgrade package.

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

   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, run ghe-repl-start to start replication.

5. On the replica instance, run ghe-repl-status to make sure replication services are running correctly. This command will return OK for all services when a successful replication is in progress and the replica has upgraded. If the command returns Replication is not running, the replication may still be starting. Wait about one minute before running ghe-repl-status again.

   Note: While the resync is in progress ghe-repl-status may return expected messages indicating that replication is behind. For example: CRITICAL: git replication is behind the primary by more than 1007 repositories and/or gists

   If ghe-repl-status didn't return OK, follow the steps below to manually start the replication.

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

   2. On the replica instance, run ghe-repl-start to start replication.

   3. On the replica instance, run ghe-repl-status to make sure replication services are running correctly. This command will return OK for all services when a successful replication is in progress and the replica has upgraded.

6. When you have completed upgrading the last replica, and the resync is complete, disable maintenance mode so users can use your GitHub Enterprise instance.

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. For more information, see "Enabling and scheduling maintenance mode."

2. To restore your boot partition, run ghe-rollback-rootfs. This command only restores the boot partition and will turn the VM off when it's finished. For more information, see "Command line utilities."

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.