docs/content/admin/upgrading-your-instance/performing-an-upgrade/upgrading-with-an-upgrade-package.md

title, intro, redirect_from, versions, type, topics, shortTitle

title	intro	redirect_from	versions	type	topics	shortTitle
Upgrading with an upgrade package	Learn how to use an upgrade package to upgrade {% data variables.product.prodname_ghe_server %} to a newer feature release.	/admin/monitoring-managing-and-updating-your-instance/updating-the-virtual-machine-and-physical-resources/upgrading-github-enterprise-server#upgrading-a-standalone-instance-using-an-upgrade-package /admin/enterprise-management/updating-the-virtual-machine-and-physical-resources/upgrading-github-enterprise-server#upgrading-with-an-upgrade-package	ghes *	how_to	Enterprise Upgrades	Upgrade with an upgrade package

Using the administrative shell, you can install an upgrade package with the ghe-upgrade utility.

If you're running back-to-back feature version upgrades, you must ensure background jobs are complete before proceeding with the following upgrade to a feature release. {% data variables.product.prodname_dotcom %} recommends waiting for any background upgrade tasks to complete before upgrading a second time. See AUTOTITLE and AUTOTITLE.

While you can use a hotpatch to upgrade to the latest patch release within a feature series, you must use an upgrade package to upgrade to a newer feature release. For example, to upgrade from 2.11.10 to 2.12.4 you must use an upgrade package since these are in different feature series.

Upgrading a standalone instance using an upgrade package

{% data reusables.enterprise_installation.download-note %}

{% data reusables.enterprise_installation.ssh-into-instance %}

1. {% data reusables.enterprise_installation.enterprise-download-upgrade-pkg %} Select the appropriate platform and copy the URL for the upgrade package (.pkg file). {% data reusables.enterprise_installation.download-package %}

2. Enable maintenance mode and wait for all active processes to complete on the {% data variables.product.prodname_ghe_server %} instance. See AUTOTITLE.

   [!NOTE] When upgrading the primary node in a high availability configuration, the instance should already be in maintenance mode if you are following the instructions in Upgrading the primary node with an upgrade package.

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

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

4. 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]
   

5. Optionally, during an upgrade to a feature release, you can monitor the status of database migrations using the ghe-migrations utility. See AUTOTITLE.

6. After the instance restarts, the upgrade will continue in the background. You cannot unset maintenance mode until the process completes.

   To check the status of background jobs, use the ghe-check-background-upgrade-jobs utility. If you're running back-to-back upgrades, you must ensure background jobs are complete before proceeding with the following upgrade to a feature release.

   See AUTOTITLE.

   To monitor progress of the configuration run, read the output in /data/user/common/ghe-config.log. For example, you can tail the log by running the following command:

   tail -f /data/user/common/ghe-config.log
   

   The configuration runs in the background and you don't need to run ghe-config-apply explicitly unless you encounter a problem.

   [!WARNING] If you are upgrading a node in a multi-node cluster, running ghe-config-apply on the command line or saving settings in the {% data variables.enterprise.management_console %} may fail and result in an incomplete upgrade if not all the nodes are upgraded to the same version. Please use ghe-single-config-apply instead.

7. Optionally, after the upgrade, validate the upgrade by configuring an IP exception list to allow access to a specified list of IP addresses. See AUTOTITLE.

8. For single node upgrades, perform any post-upgrade tasks including disabling maintenance mode so users can use {% data variables.location.product_location %}.

   [!NOTE] After you upgrade an instance in a high availability configuration, you should remain in maintenance mode until you have upgraded all of the replica nodes and replication is current. See Upgrading additional nodes with an upgrade package.

Upgrading an instance with multiple nodes using an upgrade package

To upgrade a multi-node {% data variables.product.prodname_ghe_server %} environment using an upgrade package, you must first upgrade the primary node and wait for its configuration run to complete successfully. Only after the primary is fully upgraded and configured can you proceed to upgrade any replica or additional nodes. Attempting to upgrade other nodes before the primary is complete will result in upgrade failures.

• Upgrading the primary node with an upgrade package
• Upgrading additional nodes with an upgrade package

Upgrading the primary node with an upgrade package

[!WARNING] When replication is stopped, if the primary fails, any work from before the replica is upgraded and the replication begins again will be lost.

1. On the primary node, enable maintenance mode and wait for all active processes to complete. See AUTOTITLE. {% data reusables.enterprise_installation.replica-ssh %}
2. To stop replication on all nodes, run ghe-repl-stop on each node. Alternatively, if there are multiple replicas, run ghe-repl-stop-all on the primary node instead, which will stop replication in a single run.
3. To upgrade the primary node, follow the instructions in Upgrading a standalone instance using an upgrade package.

Upgrading additional nodes with an upgrade package

1. Upgrade the node by following the instructions in Upgrading a standalone instance using an upgrade package. {% data reusables.enterprise_installation.replica-ssh %} {% data reusables.enterprise_installation.replica-verify %} {% data reusables.enterprise_installation.start-replication %} Alternatively, if there are multiple replicas, run ghe-repl-start-all on the primary node instead, which will start replications in a single run. {% data reusables.enterprise_installation.replication-status %} {% data reusables.enterprise_installation.replication-status-upgrade %} {% data reusables.enterprise_installation.multiple-node-repeat-upgrade-process %} {% data reusables.enterprise_installation.disable-maintenance-mode-after-replica-upgrade %}