Skip to main content
We publish frequent updates to our documentation, and translation of this page may still be in progress. For the most current information, please visit the English documentation.
All products
Enterprise administrators

This version of GitHub Enterprise was discontinued on 2023-03-15. 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.

Enabling subdomain isolation

In this article

You can set up subdomain isolation to securely separate user-supplied content from other portions of your GitHub Enterprise Server appliance.

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.

Path without subdomain isolationPath with subdomain isolation
http(s)://HOSTNAME/http(s)://docker.HOSTNAME/
http(s)://HOSTNAME/_registry/npm/https://npm.HOSTNAME/
http(s)://HOSTNAME/_registry/rubygems/https://rubygems.HOSTNAME/
http(s)://HOSTNAME/_registry/maven/https://maven.HOSTNAME/
http(s)://HOSTNAME/_registry/nuget/https://nuget.HOSTNAME/
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/

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. If you have changed the hostname for your instance and are experiencing problems, contact GitHub Enterprise Support or GitHub Premium Support.

  • 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 both HOSTNAME and the wildcard domain *.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 both github.octoinc.com and *.github.octoinc.com.
  • Enable TLS on your appliance. For more information, see "Configuring TLS."

Enabling subdomain isolation

  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 Hostname.

  5. Select Subdomain isolation (recommended).

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

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

  7. Wait for the configuration run to complete.