Automating an upgrade

You can upgrade your GitHub Enterprise Server instance using the Manage GitHub Enterprise Server API or the gh es extension for GitHub CLI. These tools automate the process of downloading the upgrade package, running pre-upgrade checks, and applying the new version.

Prerequisites

Back up your data with GitHub Enterprise Server Backup Utilities.
Schedule a maintenance window for end users.
Ensure you can authenticate to the Manage GitHub Enterprise Server API. For more information, see Endpoints d’API REST pour l’administration de GitHub Enterprise.

Automating an upgrade using the REST API

Download the upgrade package.

curl -L \
  -X POST \
  -u "api_key:ROOT-SITE-ADMINISTRATOR-PASSWORD" \
  -H "Content-Type: application/json" \
  https://HOSTNAME:8443/manage/v1/upgrade/download \
  -d '{"version":"VERSION"}'

Confirm the download has completed before proceeding.

curl -L \
  -u "api_key:ROOT-SITE-ADMINISTRATOR-PASSWORD" \
  -H "Content-Type: application/json" \
  https://HOSTNAME:8443/manage/v1/upgrade/download/status

Wait until status shows COMPLETED.

Apply the upgrade's pre-upgrade phase.

curl -L \
  -X POST \
  -u "api_key:ROOT-SITE-ADMINISTRATOR-PASSWORD" \
  -H "Content-Type: application/json" \
  https://HOSTNAME:8443/manage/v1/upgrade/apply \
  -d '{"version":"VERSION", "phase":"pre-upgrade"}'

Monitor the pre-upgrade phase until it completes.

curl -L \
  -u "api_key:ROOT-SITE-ADMINISTRATOR-PASSWORD" \
  -H "Content-Type: application/json" \
  "https://HOSTNAME:8443/manage/v1/upgrade/status?is_verbose=true"

Wait until status shows completed and is_running shows false.

Enable maintenance mode.

curl -L \
  -X POST \
  -u "api_key:ROOT-SITE-ADMINISTRATOR-PASSWORD" \
  -H "Content-Type: application/json" \
  https://HOSTNAME:8443/manage/v1/maintenance \
  -d '{"enabled":true}'

Apply the upgrade's upgrade phase.

curl -L \
  -X POST \
  -u "api_key:ROOT-SITE-ADMINISTRATOR-PASSWORD" \
  -H "Content-Type: application/json" \
  https://HOSTNAME:8443/manage/v1/upgrade/apply \
  -d '{"version":"VERSION", "phase":"upgrade"}'

Confirm the release version has been updated.

curl -L \
  -u "api_key:ROOT-SITE-ADMINISTRATOR-PASSWORD" \
  -H "Content-Type: application/json" \
  https://HOSTNAME:8443/manage/v1/version

Disable maintenance mode.

curl -L \
  -X POST \
  -u "api_key:ROOT-SITE-ADMINISTRATOR-PASSWORD" \
  -H "Content-Type: application/json" \
  https://HOSTNAME:8443/manage/v1/maintenance \
  -d '{"enabled":false}'

Automating an upgrade using the GitHub CLI extension

Download the upgrade package. To download a specific version, specify the --version flag; otherwise, the latest available version is downloaded.

# Download a specific version
gh es upgrade download --version VERSION

# Or download the latest available version
gh es upgrade download

Confirm the download has completed before proceeding.
```
gh es upgrade download status
```
Wait until status shows COMPLETED.

Apply the upgrade's pre-upgrade phase.

gh es upgrade apply --version VERSION --phase pre-upgrade

Monitor the pre-upgrade phase until it completes.
```
gh es upgrade status --verbose
```
Wait until status shows completed and is_running shows false.
Enable maintenance mode.
```
gh es maintenance set --enabled true
```

Apply the upgrade's upgrade phase.

gh es upgrade apply --version VERSION --phase upgrade

Confirm the release version has been updated.
```
gh es release version
```
Disable maintenance mode.
```
gh es maintenance set --enabled false
```

Upgrading a high availability deployment

For instances with a high availability (HA) replica, the download and pre-upgrade phases are non-disruptive and can run across all nodes at once. UUID targeting is only needed for the upgrade phase itself, which triggers the reboot. This lets you control the order nodes reboot in: upgrade the replica first, then the primary.

To retrieve node UUIDs, run gh es config get-metadata or query GET /manage/v1/config/nodes.

Upgrading a high availability deployment using the GitHub CLI

Download the package to all nodes.

gh es upgrade download --version VERSION

Wait for the download to complete on all nodes.
```
gh es upgrade download status
```
Run the pre-upgrade phase on all nodes at once. This phase is non-disruptive.
```
gh es upgrade apply --version VERSION --phase pre-upgrade
```
Wait for the pre-upgrade phase to complete.
```
gh es upgrade status --verbose
```
Enable maintenance mode.
```
gh es maintenance set --enabled true
```
Stop replication on the replica.
```
ghe-repl-stop
```

Upgrade the primary first, which triggers the reboot, then monitor its progress.

gh es upgrade apply --version VERSION --phase upgrade --uuid PRIMARY-UUID
gh es upgrade status --uuid PRIMARY-UUID --verbose

After the primary finishes, upgrade the replica, then monitor its progress.

gh es upgrade apply --version VERSION --phase upgrade --uuid REPLICA-UUID
gh es upgrade status --uuid REPLICA-UUID --verbose

Start replication again on the replica.
```
ghe-repl-start
```

Verify replication health and the version, then disable maintenance mode.

gh es replication status
gh es release version
gh es maintenance set --enabled false

Upgrading a high availability deployment using the REST API