About custom domains and GitHub Pages
GitHub Pages supports using custom domains, or changing the root of your site's URL from the default, like
octocat.github.io, to any domain you own.
GitHub Pages is available in public repositories with GitHub Free, and in public and private repositories with GitHub Pro, GitHub Team, GitHub Enterprise Cloud, and GitHub Enterprise Server. For more information, see "GitHub's products."
In this article
- Supported custom domains
- Using a subdomain for your GitHub Pages site
- Using an apex domain for your GitHub Pages site
- Updating custom domains when your GitHub Pages site is disabled
- Further reading
Supported custom domains
GitHub Pages works with two types of domains: subdomains and apex domains. For a list of unsupported custom domains, see "Troubleshooting custom domains and GitHub Pages."
|Supported custom domain type||Example|
You can set up either or both types of custom domains for your site. We recommend always using a
www subdomain, even if you also use an apex domain. For more information, see "Using an apex domain for your GitHub Pages site."
After you configure a custom domain for a user or organization site, the custom domain will replace the
<organization>.github.io portion of the URL for any project sites owned by the account that do not a custom domain configured. For example, if the custom domain for your user site is
www.octocat.com, and you have a project site with no custom domain configured that is published from a repository called
octo-project, the GitHub Pages site for that repository will be available at
Using a subdomain for your GitHub Pages site
A subdomain is the part of a URL before the root domain. You can configure your subdomain as
www or as a distinct section of your site, like
Subdomains are configured with a
CNAME record through your DNS provider. For more information, see "Managing a custom domain for your GitHub Pages site."
www subdomain is the most commonly used type of subdomain. For example,
www.example.com includes a
www subdomains are the most stable type of custom domain because
www subdomains are not affected by changes to the IP addresses of GitHub's servers. Your site will also load faster because Denial of Service (DoS) attack protection can be implemented more efficiently.
A custom subdomain is a type of subdomain that doesn't use the standard
www subdomain. Custom subdomains are mostly used when you want two distinct sections of your site. For example, you can create a site called
blog.example.com and customize that section independently from
Using an apex domain for your GitHub Pages site
An apex domain is a custom domain that does not contain a subdomain, such as
example.com. Apex domains are also known as base, bare, naked, root apex, or zone apex domains.
An apex domain is configured with an
ANAME record through your DNS provider. For more information, see "Managing a custom domain for your GitHub Pages site."
If you are using an apex domain as your custom domain, we recommend also setting up a
www subdomain. If you configure the correct records for each domain type through your DNS provider, GitHub Pages will automatically create redirects between the domains. For example, if you configure
www.example.com as your custom domain for your site, and you have
CNAME records set up for the apex and
www domains, then
example.com will redirect to
www.example.com. For more information, see "Managing a custom domain for your GitHub Pages site."
Updating custom domains when your GitHub Pages site is disabled
If your GitHub Pages site is disabled but has a custom domain set up, you should immediately update or remove your DNS records with your DNS provider to avoid the risk of a domain takeover. Having a custom domain configured with your DNS provider while your site is disabled could result in someone else hosting a site on one of your subdomains. For more information, see "Managing a custom domain for your GitHub Pages site."
There are a couple of reasons your site might be automatically disabled.
- If you downgrade from GitHub Pro to GitHub Free, any GitHub Pages sites that are currently published from private repositories in your account will be unpublished. For more information, see "Downgrading your GitHub billing plan."
- If you transfer a private repository to a personal account that is using GitHub Free, the repository will lose access to the GitHub Pages feature, and the currently published GitHub Pages site will be unpublished. For more information, see "Transferring a repository."