About subdomain isolation
Subdomain isolation mitigates cross-site scripting and other related vulnerabilities. For more information, see "Cross-site scripting" on Wikipedia. We highly recommend that you enable subdomain isolation on your GitHub Enterprise Server instance.
When subdomain isolation is enabled, GitHub Enterprise Server replaces several paths with subdomains. After enabling subdomain isolation, attempts to access the previous paths for some user-supplied content, such as http(s)://HOSTNAME/raw/
, may return 404
errors.
To use Docker with GitHub Packages, you must also enable subdomain isolation. For more information, see "Working with the Docker registry."
Note: GitHub Packages is currently in beta for GitHub Enterprise Server 2.22. To join the beta for your GitHub Enterprise Server instance, use the sign-up form.
Path without subdomain isolation | 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/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/ |
N/A, Docker with GitHub Packages will not work with subdomain isolation disabled for the GitHub Packages 2.22 beta. | http(s)://docker.HOSTNAME/ |
Prerequisites
Warning: If subdomain isolation is disabled, we recommend also disabling GitHub Pages on your enterprise. There will be no way to isolate user-supplied GitHub Pages content from the rest of your enterprise's data. For more information, see "Configuring GitHub Pages for your enterprise."
Before you enable subdomain isolation, you must configure your network settings for your new domain.
- Specify a valid domain name as your hostname, instead of an IP address. For more information, see "Configuring a hostname."
Warning: Do not change the hostname for GitHub Enterprise Server after initial setup. Changing the hostname will cause unexpected behavior, up to and including instance outages.
- Set up a wildcard Domain Name System (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 Transport Layer Security (TLS) certificate for
*.HOSTNAME
with a Subject Alternative Name (SAN) for bothHOSTNAME
and the wildcard domain*.HOSTNAME
. For example, if your hostname isgithub.octoinc.com
, get a certificate with the Common Name value set to*.github.octoinc.com
and a SAN value set to bothgithub.octoinc.com
and*.github.octoinc.com
. - Enable TLS on your appliance. For more information, see "Configuring TLS."
Enabling subdomain isolation
- From an administrative account on GitHub Enterprise Server, click in the upper-right corner of any page.
- In the left sidebar, click Management Console.
- In the left sidebar, click Hostname.
- Select Subdomain isolation (recommended).
- Under the left sidebar, click Save settings.
- Wait for the configuration run to complete.