How To Use DigitalOcean's DNS For Custom GitHub URLs

Published on April 30, 2014

Assaf Gordon

How To Use DigitalOcean's DNS For Custom GitHub URLs


This tutorial shows how to setup a DNS redirection from your own custom domain (e.g. http://githubtest.teamerlich.org/) to point to your GitHub-hosted static website (e.g. http://agordon.github.io/custom_dns_test) using DigitalOcean’s DNS control panel.

Github Pages enable every project hosted on GitHub to have a dedicated static website for the program. Setting up a static website is explained in detail on the their website (and even include an automatic template generator to help one setup a new website).

The default URL for such a website is based on the user’s name and the project’s name. For example, if the GitHub username is agordon and the project’s name is custom_dns_test, the Github repository URL will be https://github.com/agordon/custom_dns_test and the GitHub-Pages static website will be http://agordon.github.io/custom_dns_test/.

Following the directions in this tutorial, you will setup a custom domain name (e.g. http://githubtest.teamerlich.org/) which will be an autmatic alias to http://agordon.github.io/custom_dns_test/ - that is, users visiting the custom URL will see the content of http://agordon.github.io/custom_dns_test/ (stored on and served by GitHub’s servers) but the URL will be your custom one.

This article follows GitHub’s Custom Domain with Github Pages tutorial, adapted for DigitanOcean’s DNS control panel.


This tutorial assumes you have the followings:

  1. A registered domain name (e.g. teamerlich.org) at a domain registrar ( such as godaddy.com ).

  2. Proper DNS configuration in DigitalOcean’s nameservers.

    See article for basic domain name with DigitalOcean and Sub-domains in DigitalOcean.

  3. A user on GitHub.

    Example: If your GitHub user is agordon your Github page will be https://github.com/agordon/.

  4. A Github project which you own (and can modify).

    Example: if your GitHub project is custom_dns_test, your project’s GitHub repository will be https://github.com/agordon/custom_dns_test.

  5. In said project, a GitHub-Pages setup using a branch named gh-pages. If you have not yet created a GitHub pages brunch, follow the instruction at https://pages.github.com/ (which also include an automatic website generator with beautiful templates).

Example: If your GitHub project is custom_dns_test, your project’s GitHub Pages branch repository will be https://github.com/agordon/custom_dns_test/tree/gh-pages.

Step 1 - Decide On A Subdomain Name.

The subdomain name should be alpha-numeric. You could always change the domain name later, by repeating steps 2 & 3 with the new name.

Step 2 - Add “CNAME” File To Your GitHub Project

In your GitHub project’s gh-pages branch, create (or update) a file called CNAME. The file should contain a single line with the full domain name (e.g. githubtest.teamerlich.org). The name must match the domain name you’ll setup in step 3.

Use the following commands on your local workstation to add the CNAME file. Replace the example with your own:

git pull origin
git checkout gh-pages
echo "githubtest.teamerlich.org" > CNAME
git add CNAME
git commit -m "Added CNAME for GitHub Pages"
git push

The final result should look like the following project (note the CNAME file): https://github.com/agordon/custom_dns_test/tree/gh-pages.

After uploading a new CNAME file to github, it can take up to ten minutes for GitHub servers to be updated.

Step 3 - Add DNS Record In DigitalOcean’s DNS Control Panel

In your DigitalOcean Control Panel, select Networking and then click on your domain. We need to add a new record that looks like this:

Fill in the following items:

  1. Choose CNAME as the new DNS record
  2. Enter the HOSTNAME (without a dot). The name must match the content of the CNAME file in your GitHub repository from step 2
  3. Enter the domain for your GitHub pages username in the IS AN ALIAS OF field (e.g. if your GitHub user is agordon, your GitHub-Pages server will be agordon.github.io). NOTE: the period after “io” is required
  4. Click Create Record to add the new record

Step 4 - Wait For DigitalOcean’s Server To Update

It may take several minutes for the DNS information to be updated in DigitalOcean’s DNS.

After the zone information is updated, it can still take several hours until the change is updated in other DNS servers (e.g. your ISP’s DNS server).

Examples Summary

Further information

<div class=“author”>Submitted by: <a href=“https://github.com/agordon”>Assaf Gordon</a></div>

Thanks for learning with the DigitalOcean Community. Check out our offerings for compute, storage, networking, and managed databases.

Learn more about our products

About the authors
Default avatar
Assaf Gordon


Still looking for an answer?

Ask a questionSearch for more help

Was this helpful?

This textbox defaults to using Markdown to format your answer.

You can type !ref in this text area to quickly search our full set of tutorials, documentation & marketplace offerings and insert the link!

How would I make an SSL certificate so I can use HTTPS with my Github pages site?

This was really helpful.


Kamal Nasser
DigitalOcean Employee
DigitalOcean Employee badge
July 17, 2014

@alishaaukani+digoc: In that case, you need to delete your existing @ A record and add two A records like this:

@ A
@ A

Hey, thanks for this! What if I want the regular URL (so not a subdomain) to point to the site hosted by GitHub Pages? Should I still use a CNAME, and do I need to configure my droplet to do this?

Try DigitalOcean for free

Click below to sign up and get $200 of credit to try our products over 60 days!

Sign up

Join the Tech Talk
Success! Thank you! Please check your email for further details.

Please complete your information!

Featured on Community

Get our biweekly newsletter

Sign up for Infrastructure as a Newsletter.

Hollie's Hub for Good

Working on improving health and education, reducing inequality, and spurring economic growth? We'd like to help.

Become a contributor

Get paid to write technical tutorials and select a tech-focused charity to receive a matching donation.

Welcome to the developer cloud

DigitalOcean makes it simple to launch in the cloud and scale up as you grow — whether you're running one virtual machine or ten thousand.

Learn more
DigitalOcean Cloud Control Panel