How To Use DigitalOcean's DNS For Custom GitHub URLs

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.

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

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:

cd [PROJECT-DIRECTORY]
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.

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

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

• GitHub Project’s Page: https://github.com/agordon/custom_dns_test
• GitHub-Pages with github-based URL: http://agordon.github.io/custom_dns_test/
• Same content as above with custom URL http://githubtest.teamerlich.org/
• GitHub project’s gh-pages branch: https://github.com/agordon/custom_dns_test/tree/gh-pages
• CNAME file containing the custom URL: https://github.com/agordon/custom_dns_test/blob/gh-pages/CNAME

• GitHub Pages - https://pages.github.com/
• GitHub Pages Custom DNS - https://help.github.com/articles/setting-up-a-custom-domain-with-github-pages
• DigitalOcean’s DNS basics - https://www.digitalocean.com/community/articles/how-to-set-up-a-host-name-with-digitalocean
• DigitalOcean’s DNS subdomains - https://www.digitalocean.com/community/articles/how-to-set-up-and-test-dns-subdomains-with-digitalocean-s-dns-panel

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