gh-pages: Make Sure CNAME Is In Your Repository Root!

Published: December 19, 2013

I recently ran into an issue when deploying WhatsPopularOnYouTube.com, an AngularJS app that displays a live feed of the most popular videos on YouTube.

The app was scaffolded with the Angular Seed Project, which offers a nice starting structure for Angular apps. When using the Angular Seed Project the document root for the app is the app directory, which is one level above the repository root.

app/
  css/
    app.css
  img/
  index.html ←-In app directory, one level above repository root
  index-async.html
  js/
    app.js
    controllers.js
    directives.js
    filters.js
    services.js
  lib/
    angular/
      angular.js
      angular.min.js
      angular-*.js
      version.txt
  partials/
    partial1.html
    partial2.html
config/
  karma.conf.js
  karma-e2e.conf.js
scripts/
  e2e-test.sh
  e2e-test.bat
etc…

Since the app doesn't involve any server side coding, and a database is not needed, I wanted to use Github pages for hosting. My original plan was to push the entire repository up to Github and put the CNAME file in the app directory, one level above the repository root. I figured this would work since I had seen something similar in the Jekyll repository, where there is a CNAME file in the site directory, one level above the repository root.

I pushed the repository up, with the CNAME file in place, updated the A record at my registrar, and refreshed the page for about 10 minutes, only to continue getting a generic Github 404 error. I re-checked the A record at the registrar, re-checked the spelling on in my CNAME file, but everything was done properly. Finally, after Googling terms like 'github pages CNAME subdirectory' and learning nothing, I decided to contact Github about the issue

Much to my surprise, I received the following response...

Your CNAME file definitely needs to be in the root of the repository.

So I made that change and within 10 minutes my site was up and running.

The point of this blog post is to help out anyone who might have a similar idea about putting the CNAME file in a directory outside of the repository root. For example, someone who has seen the Jekyll repository (which has over 13,000 stars on Github at the time of writing this), might be inclined to think that the CNAME file could be placed there.

Since all the searches I ran on Google provided no quick guidance on this issue, hopefully this blog post will help someone out.