|
| 1 | +--- |
| 2 | +title: Rotating the signing key for upgrade packages |
| 3 | +intro: 'Learn how to rotate the GPG public key on {% data variables.product.prodname_ghe_server %} when {% data variables.product.company_short %} updates the key used to sign upgrade packages.' |
| 4 | +versions: |
| 5 | + ghes: '*' |
| 6 | +shortTitle: Rotate upgrade signing key |
| 7 | +contentType: how-tos |
| 8 | +category: |
| 9 | + - Back up and upgrade your instance |
| 10 | +--- |
| 11 | + |
| 12 | +## About upgrade package signing keys |
| 13 | + |
| 14 | +{% data variables.product.prodname_ghe_server %} upgrade packages are signed with a GPG key so that administrators can verify the packages come from {% data variables.product.company_short %}. When you install an upgrade, the appliance checks the package signature against the GPG public key stored in its keyring. |
| 15 | + |
| 16 | +Occasionally, {% data variables.product.company_short %} may rotate this signing key. When that happens, you must update the GPG public key on your instance before you can install any upgrade packages signed with the new key. Your instance will continue to function normally without the key rotation, but upgrades will fail signature verification until the key is updated. |
| 17 | + |
| 18 | +If the signing key has not been rotated, attempting to install an upgrade package will fail with the following error: |
| 19 | + |
| 20 | +```text |
| 21 | +Error: The file provided is not a valid GitHub Enterprise Server package. |
| 22 | +``` |
| 23 | + |
| 24 | +## Considerations for unsupported versions |
| 25 | + |
| 26 | +{% data variables.product.company_short %} strongly recommends upgrading to a supported version as soon as possible. |
| 27 | + |
| 28 | +Versions of {% data variables.product.prodname_ghe_server %} prior to 3.16 are not being re-signed with the new GPG key. If you are on version 3.13 or earlier you will not be able to rotate the GPG public key until you are on at least version 3.14. If you rotate your GPG public key before upgrading to at least 3.14 you will not be able to install upgrades, as the prior GPG public key will be removed from your {% data variables.product.prodname_ghe_server %} instance. |
| 29 | + |
| 30 | +For help determining the correct upgrade path, use the [{% data variables.enterprise.upgrade_assistant %}](https://support.github.com/enterprise/server-upgrade). |
| 31 | + |
| 32 | +## Prerequisites |
| 33 | + |
| 34 | +* SSH access to your {% data variables.product.prodname_ghe_server %} instance. For more information, see [AUTOTITLE](/admin/administering-your-instance/accessing-the-administrative-shell-ssh). |
| 35 | +* Your instance must be able to reach `enterprise.github.com` over HTTPS to download the rotation script. If your instance is behind a restrictive firewall or in an air-gapped environment, download the script from an external machine and transfer it to the appliance manually. |
| 36 | + |
| 37 | +## Rotating the signing key on a single-node instance |
| 38 | + |
| 39 | +1. Connect to your {% data variables.product.prodname_ghe_server %} instance via SSH. |
| 40 | +1. Download the rotation script provided by {% data variables.product.company_short %}. |
| 41 | + |
| 42 | + ```shell |
| 43 | + curl -fsSL https://enterprise.github.com/security/2026-05-24/rotate-gpg.sh -o rotate-gpg.sh |
| 44 | + ``` |
| 45 | + |
| 46 | +1. Run the rotation script. The script must be run twice: once as the `admin` user and once with `sudo`, because the key is stored in both the admin and root accounts. |
| 47 | + |
| 48 | + ```shell |
| 49 | + chmod ug+x ./rotate-gpg.sh |
| 50 | + ./rotate-gpg.sh |
| 51 | + sudo ./rotate-gpg.sh |
| 52 | + ``` |
| 53 | + |
| 54 | +1. Verify the rotation completed successfully. Each run of the script prints a confirmation message that includes the new key fingerprint. |
| 55 | + |
| 56 | +## Rotating the signing key on HA or cluster topologies |
| 57 | + |
| 58 | +For instances configured with high availability or clustering, the key must be rotated on every node. |
| 59 | + |
| 60 | +1. Connect to any node in your HA or cluster installation via SSH. |
| 61 | +1. Download the rotation script provided by {% data variables.product.company_short %}. |
| 62 | + |
| 63 | + ```shell |
| 64 | + curl -fsSL https://enterprise.github.com/security/2026-05-24/rotate-gpg.sh -o rotate-gpg.sh |
| 65 | + ``` |
| 66 | + |
| 67 | +1. Run the following commands. The `ghe-cluster-each` command copies the script to all nodes and runs it on all nodes. |
| 68 | + |
| 69 | + ```shell |
| 70 | + ghe-cluster-each -- chmod ug+x ./rotate-gpg.sh |
| 71 | + ghe-cluster-each -- ./rotate-gpg.sh |
| 72 | + ghe-cluster-each -- sudo ./rotate-gpg.sh |
| 73 | + ``` |
| 74 | + |
| 75 | +1. Verify the rotation completed successfully on each node. |
| 76 | + |
| 77 | +## Verifying the current signing key |
| 78 | + |
| 79 | +To check which GPG signing key is currently installed on your instance, connect via SSH and run: |
| 80 | + |
| 81 | +```shell |
| 82 | +gpg --list-keys --keyid-format long |
| 83 | +``` |
| 84 | + |
| 85 | +The output displays the fingerprint of the key in the keyring. Compare the fingerprint with the expected value published by {% data variables.product.company_short %} to confirm the rotation was applied correctly. |
| 86 | + |
| 87 | +## What to expect after rotating the key |
| 88 | + |
| 89 | +After you rotate the signing key: |
| 90 | + |
| 91 | +* Your instance continues to function normally. No user downtime is required. |
| 92 | +* Previously downloaded upgrade packages that were signed with the prior key will fail verification. Download the latest available patch release to get a package signed with the new key. |
| 93 | +* Only download {% data variables.product.prodname_ghe_server %} updates from the official releases page. For more information, see [{% data variables.product.prodname_ghe_server %} releases](https://enterprise.github.com/releases). |
| 94 | + |
| 95 | +## Reverting a key rotation |
| 96 | + |
| 97 | +The rotation script removes the previous key from the GPG keyring before importing the new key. There is no built-in way to undo the rotation. |
| 98 | + |
| 99 | +If you need assistance reverting a key rotation or recovering from a failed upgrade, [contact {% data variables.contact.github_support %}](/support/contacting-github-support). |
0 commit comments