This version of GitHub Enterprise was discontinued on 2020-11-12. No patch releases will be made, even for critical security issues. For better performance, improved security, and new features, upgrade to the latest version of GitHub Enterprise. For help with the upgrade, contact GitHub Enterprise support.

Using GitHub Enterprise Server with a load balancer

Use a load balancer in front of a single GitHub Enterprise Server appliance or a pair of appliances in a High Availability configuration.

In this article

A load balancer design uses a network device to direct Git and HTTP traffic to individual GitHub Enterprise Server appliances. You can use a load balancer to restrict direct traffic to the appliance for security purposes or to redirect traffic if needed without DNS record changes. We strongly recommend using a TCP-based load balancer that supports the PROXY protocol.

DNS lookups for the GitHub Enterprise Server hostname should resolve to the load balancer. We recommend that you enable subdomain isolation. If subdomain isolation is enabled, an additional wildcard record (*.HOSTNAME) should also resolve to the load balancer. For more information, see "Enabling subdomain isolation."

Handling client connection information

Because client connections to GitHub Enterprise Server come from the load balancer, the client IP address can be lost.

If your load balancer can support it, we strongly recommend implementing the PROXY protocol. When no PROXY support is available, it is also possible to load balance the HTTP and HTTPS ports using the X-Forwarded-For header.

Security Warning: When either PROXY support or HTTP forwarding is enabled, it is critical that no external traffic can directly reach the GitHub Enterprise Server appliances. If external traffic is not properly blocked, the source IP addresses can be forged.

Enabling PROXY protocol support on your GitHub Enterprise Server instance

We strongly recommend enabling PROXY protocol support for both your appliance and the load balancer. Use the instructions provided by your vendor to enable the PROXY protocol on your load balancer. For more information, see the PROXY protocol documentation.

  1. From an administrative account on GitHub Enterprise Server, click in the upper-right corner of any page.
    Rocketship icon for accessing site admin settings
  2. In the left sidebar, click Management Console.
    Management Console tab in the left sidebar
  3. In the left sidebar, click Privacy.
    Privacy tab in the settings sidebar
  4. Under External load balancers, select Enable support for PROXY protocol.
    Checkbox to enable support for PROXY protocol
  5. Under the left sidebar, click Save settings.
    The Save settings button in the Management Console
  6. Wait for the configuration run to complete.
PROXY protocol TCP port mappings
Source portDestination portService description
2223Git over SSH
8081HTTP
443444HTTPS
80808081Management Console HTTP
84438444Management Console HTTPS
94189419Git

Enabling X-Forwarded-For support on your GitHub Enterprise Server instance

Use the X-Forwarded-For protocol only when the PROXY protocol is unavailable. The X-Forwarded-For header only works with HTTP and HTTPS. The IP address reported for Git connections over SSH will show the load balancer IP.

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.

  1. From an administrative account on GitHub Enterprise Server, click in the upper-right corner of any page.
    Rocketship icon for accessing site admin settings
  2. In the left sidebar, click Management Console.
    Management Console tab in the left sidebar
  3. In the left sidebar, click Privacy.
    Privacy tab in the settings sidebar
  4. Under External load balancers, select Allow HTTP X-Forwarded-For header.
    Checkbox to allow the HTTP X-Forwarded-For header
  5. Under the left sidebar, click Save settings.
    The Save settings button in the Management Console
  6. Wait for the configuration run to complete.
Protocol TCP port mappings for use without PROXY support
Source portDestination portService description
2222Git over SSH
2525SMTP
8080HTTP
443443HTTPS
80808080Management Console HTTP
84438443Management Console HTTPS

Configuring health checks

Health checks allow a load balancer to stop sending traffic to a node that is not responding if a pre-configured check fails on that node. If the appliance is offline due to maintenance or unexpected failure, the load balancer can display a status page. In a High Availability (HA) configuration, a load balancer can be used as part of a failover strategy. However, automatic failover of HA pairs is not supported. You must manually promote the replica appliance before it will begin serving requests. For more information, see "Configuring GitHub Enterprise Server for High Availability."

Configure the load balancer to check one of these URLs:

  • https://HOSTNAME/status if HTTPS is enabled (default)
  • http://HOSTNAME/status if HTTPS is disabled

The check will return status code 200 (OK) if the node is healthy and available to service end-user requests.

Note: When the appliance is in maintenance mode, the https://HOSTNAME/status URL will return status code 503 (Service Unavailable). For more information, see "Enabling and scheduling maintenance mode."