Configuring TLS

You can configure Transport Layer Security (TLS) on your GitHub Enterprise Server instance so that you can use a certificate that is signed by a trusted certificate authority.

In this article

About Transport Layer Security

TLS, which replaced SSL, is enabled and configured with a self-signed certificate when GitHub Enterprise Server is started for the first time. As self-signed certificates are not trusted by web browsers and Git clients, these clients will report certificate warnings until you disable TLS or upload a certificate signed by a trusted authority, such as Let's Encrypt.

The GitHub Enterprise Server appliance will send HTTP Strict Transport Security headers when SSL is enabled. Disabling TLS will cause users to lose access to the appliance, because their browsers will not allow a protocol downgrade to HTTP. For more information, see HTTP Strict Transport Security (HSTS) on Wikipedia.

Warning

When terminating HTTPS connections on a load balancer, the requests from the load balancer to GitHub Enterprise Server also need to use HTTPS. Downgrading the connection to HTTP is not supported.

To allow users to use FIDO U2F for two-factor authentication or deploy GitHub Pages sites with GitHub Actions, you must enable TLS for your instance. For more information, see Configuring two-factor authentication.

Prerequisites

To use TLS in production, you must have a certificate in an unencrypted PEM format signed by a trusted certificate authority. To use a certificate signed by an internal certificate authority, you must install the root certificate and any intermediate certificates. For more information, see Troubleshooting TLS errors.

Your certificate will also need Subject Alternative Names configured for the subdomains listed in Enabling subdomain isolation and will need to include the full certificate chain if it has been signed by an intermediate certificate authority. For more information, see Subject Alternative Name on Wikipedia.

You can generate a certificate signing request (CSR) for your instance using the ghe-ssl-generate-csr command. For more information, see Command-line utilities.

Your key must be an RSA key and must not have a passphrase. For more information, see Troubleshooting TLS errors.

Uploading a custom TLS certificate

Warning

Configuring TLS causes a small amount of downtime for your GitHub Enterprise Server instance.

  1. From an administrative account on GitHub Enterprise Server, in the upper-right corner of any page, click .

  2. If you're not already on the "Site admin" page, in the upper-left corner, click Site admin.

  3. In the " Site admin" sidebar, click Management Console.

  4. In the "Settings" sidebar, click Privacy and uncheck Privacy mode.

  5. Select TLS only (recommended).

  6. Under "TLS Protocol support", select the protocols you want to allow.

  7. Under "Certificate", click Choose File, then choose a TLS certificate or certificate chain (in PEM format) to install. This file will usually have a .pem, .crt, or .cer extension.

  8. Under "Unencrypted key", click Choose File, then choose an RSA key (in PEM format) to install. This file will usually have a .key extension.

  9. Under the "Settings" sidebar, click Save settings.

    Note

    Saving settings in the Management Console restarts system services, which could result in user-visible downtime.

  10. Wait for the configuration run to complete.

About Let's Encrypt support

Let's Encrypt is a public certificate authority that issues free, automated TLS certificates that are trusted by browsers using the ACME protocol. You can automatically obtain and renew Let's Encrypt certificates on your appliance without any required manual maintenance.

To use Let's Encrypt automation, your appliance must be configured with a hostname that is publicly accessible over HTTP. The appliance must also be allowed to make outbound HTTPS connections.

When you enable automation of TLS certificate management using Let's Encrypt, your GitHub Enterprise Server instance will contact the Let's Encrypt servers to obtain a certificate. To renew a certificate, Let's Encrypt servers must validate control of the configured domain name with inbound HTTP requests.

You can also use the ghe-ssl-acme command line utility on your GitHub Enterprise Server instance to automatically generate a Let's Encrypt certificate. For more information, see Command-line utilities.

Configuring TLS using Let's Encrypt

To use Let's Encrypt automation, your appliance must be configured with a hostname that is publicly accessible over HTTP. The appliance must also be allowed to make outbound HTTPS connections.

Warning

Configuring TLS causes a small amount of downtime for your GitHub Enterprise Server instance.

  1. From an administrative account on GitHub Enterprise Server, in the upper-right corner of any page, click .

  2. If you're not already on the "Site admin" page, in the upper-left corner, click Site admin.

  3. In the " Site admin" sidebar, click Management Console.

  4. In the "Settings" sidebar, click Privacy and uncheck Privacy mode.

  5. Select TLS only (recommended).

  6. Select Enable automation of TLS certificate management using Let's Encrypt.

  7. Under the "Settings" sidebar, click Save settings.

    Note

    Saving settings in the Management Console restarts system services, which could result in user-visible downtime.

  8. Wait for the configuration run to complete.

  9. In the "Settings" sidebar, click Privacy and uncheck Privacy mode.

  10. Click Request TLS certificate.

  11. Wait for the "Status" to change from "STARTED" to "DONE".

    Screenshot of the "Requesting TLS Certificate" dialog. At the top of the dialog, "STATUS: DONE" is highlighted with an orange outline.

  12. Click Save configuration.

Troubleshooting TLS with Let's Encrypt

You can troubleshoot issues that affect your TLS certificate from Let's Encrypt.

Error: "Security error prevented the resource from being loaded"

In some cases, end users may report that pages for services on your GitHub Enterprise Server instance respond with the following error in a browser's developer tools.

Security error prevented the resource from being loaded

To resolve these errors, you must update the Subject Alternative Names (SANs) your Let's Encrypt certificate by reissuing the certificate. Replacement of an instance's certificate requires user-facing downtime.

  1. Communicate the upcoming downtime to your users, and consider enabling maintenance mode. For more information, see the following articles.

  2. SSH into your GitHub Enterprise Server instance. If your instance comprises multiple nodes, for example if high availability or geo-replication are configured, SSH into the primary node. If you use a cluster, you can SSH into any node. Replace HOSTNAME with the hostname for your instance, or the hostname or IP address of a node. For more information, see "Accessing the administrative shell (SSH)."

    Shell
    ssh -p 122 admin@HOSTNAME

  3. To disable Let's Encrypt, run the following command.

    Shell
    ghe-ssl-acme -d

  4. To clear the existing settings for Let's Encrypt, run the following command.

    Shell
    ghe-ssl-acme -x

  5. To request and install a new certificate from Let's Encrypt, run the following command.

    Shell
    ghe-ssl-acme -e

  6. To apply the configuration, run the following command.

    Note

    During a configuration run, services on your GitHub Enterprise Server instance may restart, which can cause brief downtime for users.

    Shell
    ghe-config-apply

  7. Wait for the configuration run to complete.

  8. If you configured a user message or maintenance mode, remove the message and disable maintenance mode.