GitHub Pages is a fantastic hosting service offered by GitHub, allowing users to create and host static websites directly from their repositories. While GitHub provides a default domain for your GitHub Pages site, linking a custom domain to your GitHub Pages repository can give your website a more professional and personalized touch. In this article, we will guide you through linking a custom domain to your GitHub Pages site, from start to finish.

Step 1: Choose and Purchase a Custom Domain

The first step is selecting and purchasing a domain name. Various domain registrars like GoDaddy, Namecheap, or Google Domains offer domain registration services. Choose a domain name that reflects your website's purpose and is easy to remember. For this guide, we will use the placeholder yourdomain.com.

Step 2: Configure DNS Settings

Once you have purchased your custom domain, configure the DNS settings to point to GitHub Pages:

  1. Log in to your domain registrar's website and navigate to the DNS management section (often labeled "DNS Management," "DNS Settings," or "Domain Management").
  2. Locate the DNS settings for your domain. You should see a table or list of DNS records.
  3. Add a new record. Select the option to create a new record.
  4. Create a CNAME record. In the "Host" or "Name" field, enter the subdomain you want to link (e.g. www for www.yourdomain.com). In the "Value," "Points to," or "Destination" field, enter your GitHub Pages URL: username.github.io (replace "username" with your GitHub username).
  5. Save the CNAME record.

Example:

  • Host: www
  • Value: username.github.io
CNAME record example

(Optional) To link your root domain (yourdomain.com) directly to GitHub Pages, add an A record:

  • Leave the "Host" or "Name" field blank or enter @
  • In the "Value" or "Points to" field, enter one of GitHub's IP addresses: 185.199.108.153, 185.199.109.153, 185.199.110.153, or 185.199.111.153
  • Save the A record. The @ symbol represents the root domain (yourdomain.com).

Save all changes to your DNS settings.

Step 3: Add CNAME File to Your GitHub Pages Repository

You can also link your custom domain by adding a CNAME file in your repository:

  1. In your GitHub Pages repository, create a new file named CNAME (uppercase).
  2. Open the CNAME file and enter your custom domain (e.g. yourdomain.com) in plain text.
  3. Save the CNAME file.
  4. Commit the changes to your repository, including the newly created CNAME file.

GitHub Pages will automatically recognize the CNAME file and associate your custom domain with the repository. Note: This method only works if you have already configured the DNS settings as described in Step 2.

Remember to allow some time for the changes to propagate globally. It may take up to 24 to 48 hours for the DNS changes to take full effect.

Step 4: Add Custom Domain in GitHub Pages Settings

Note: A CNAME file in your repository does not automatically add or remove a custom domain. You must configure the custom domain through your repository settings or through the API. For more information, see Managing a custom domain for your GitHub Pages site and the Pages API reference.

To add your custom domain in the GitHub Pages settings for your repository, follow these steps:

  1. Open your GitHub repository and go to the "Settings" tab.
  2. Scroll down to the "GitHub Pages" section.
  3. In the "Custom domain" field, enter your custom domain (e.g. yourdomain.com).
  4. Click "Save." GitHub will validate the custom domain and configure the necessary settings.
GitHub Pages Custom Domain section example

GitHub will validate the custom domain and configure the necessary settings. Once the configuration is complete, your custom domain will be associated with your GitHub Pages site.

For more detailed information and troubleshooting tips, refer to the official GitHub documentation:

Congratulations! You have successfully linked your custom domain (yourdomain.com) to your GitHub Pages site using the CNAME file within your repository.