Setting DNS nameservers

GitHub Enterprise automatically configures DNS settings on AWS and other DHCP environments, using nameservers provided in DHCP leases. To configure a static IP, you must enter a nameserver at the beginning of your DHCP configuration process.

If your company has internal nameservers that aren't advertised over DHCP, you can apply a custom nameserver. These custom nameservers must be able to resolve your GitHub Enterprise hostname.

Manually configuring nameservers

If your DHCP server does not include nameservers, or if you need to use custom nameservers that are different than your DHCP server's leases, you can configure an alternate DNS manually:

1. As a site admin, SSH into your GitHub Enterprise instance:

   ssh -p 122 admin@hostname
   

2. To edit your nameservers, enter sudo vim /etc/resolvconf/resolv.conf.d/head.

3. Append any nameserver entries, then save the file.

4. After verifying your changes, save the file.

5. To have GitHub Enterprise incorporate the new additions, enter sudo restart resolvconf.

Hostname

We recommend setting a hostname for your appliance instead of using a hard-coded IP address. This lets you change the physical hardware that GitHub Enterprise runs on without affecting users or the client software. With a hostname set, you can also enable subdomain isolation.

Setting your hostname

1. Access the Management Console.

2. At the top of the Management Console, click Settings.

3. In the left sidebar, click Hostname.

4. In the hostname field, type the hostname of your GitHub Enterprise instance.

Subdomain Isolation

Subdomain isolation securely separates user-supplied content from other portions of your GitHub Enterprise appliance. This mitigates cross-site scripting and other related vulnerabilities.

We highly recommend that you enable subdomain isolation.

When subdomain isolation is enabled, GitHub Enterprise replaces several paths with subdomains:

Original Path	With subdomain isolation
http(s)://hostname/assets/	http(s)://assets.hostname/
http(s)://hostname/avatars/	http(s)://avatars.hostname/
http(s)://hostname/codeload/	http(s)://codeload.hostname/
http(s)://hostname/gist/	http(s)://gist.hostname/
http(s)://hostname/gist-assets/	http(s)://gist-assets.hostname/
http(s)://hostname/gist-raw/	http(s)://gist-raw.hostname/
http(s)://hostname/media/	http(s)://media.hostname/
http(s)://hostname/pages/	http(s)://pages.hostname/
http(s)://hostname/raw/	http(s)://raw.hostname/
http(s)://hostname/render/	http(s)://render.hostname/
http(s)://hostname/reply/	http(s)://reply.hostname/
http(s)://hostname/uploads/	http(s)://uploads.hostname/

If you decide to enable subdomain isolation, you will also need to:

• Specify a valid domain name as your hostname (instead of an IP address).
• Set up a wildcard DNS record or individual DNS records for the subdomains listed above. We recommend creating an A record for *.[hostname] that points to your server's IP address so you don't have to create multiple records for each subdomain.
• Get a wildcard SSL certificate for *.[hostname] with a Subject Alternative Name (SAN) for [hostname]. For example, if your hostname is github.octoinc.com, get a certificate with the Common Name value set to *.github.octoinc.com and a SAN value set to github.octoinc.com.
• Enable SSL on your appliance.

Enabling subdomain isolation

1. Access the Management Console.

2. At the top of the Management Console, click Settings.

3. In the left sidebar, click Hostname.

4. Select Subdomain isolation (recommended).

SSL

SSL is enabled and configured with a self-signed certificate when GitHub Enterprise 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 SSL or upload a certificate signed by a trusted authority. To allow users to use FIDO U2F authentication, you must enable SSL for your instance.

To use SSL in production, you must have a certificate in an unencrypted PEM format signed by a trusted certificate authority. Your certificate will also need Subject Alternative Names (SANs) configured for the subdomains listed above and will need to include the full certificate chain if it has been signed by an intermediate certificate authority.

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

Enabling SSL

1. Access the Management Console.

2. At the top of the Management Console, click Settings.

3. In the left sidebar, click Privacy.

4. Select SSL only (recommended).

5. Under Install SSL Certificate (replace existing), click Choose File.

6. Choose an SSL certificate or certificate chain (in PEM format) to install. This file will usually have a .pem, .crt, or .cer extension.

7. Under Install SSL Key (replace existing), click Choose File.

8. Choose an SSL key (in PEM format) to install. This file will usually have a .key extension.

   Warning: Your SSL key must not have a passphrase! For more information, see "Removing the passphrase from your key file".