GitHub Pages and 'page build failed' with Submodules

After a couple of days of going back and forth with GitHub Pages help,
everything is properly working!

The Symptoms

There were a couple of issues serving my website out of GH Pages. My entire website is served out of GitHub, and this blog is served as a subdirectory of the root URL - thus necessitating that it is a git submodule. More on this later.

The issues I was having were:

  1. Changes pushed to files in my root-level directory (e.g., index.html), where not being reflected in the served webpage. The source on GitHub clearly showed my changes, but the served page was never updated.

  2. As I detailed in this post, every time I pushed my website I received a 'page build failed' error:

     The page build failed with the following error:
     page build failed
     For information on troubleshooting Jekyll see
     If you have any questions please contact GitHub Support.


The first one really threw me off. A build error on my blog would explain my blog not getting updated, but in fact, my blog was being updated. It would throw an error, but still work. Bizarrely, it was the files in my root directory, completely independent of the blog, that wouldn't reflect new changes.

My Setup

The situation was caused primarily by the fact that this blog is served out of a git submodule, and thus a subdirectory, of my actual root GitHub pages repo. This is illustrated below:

       +------------------+         +--------+          +------------+
       ||         |blog.git|          |octoblog.git|
       +------------------+         +--------+          +------------+
        |                             ^    ^                        |
        +------> index.html           |    |                        |
        +------> <various>            |    |                        |
        +------> /blog +--------------+    +-+"rake deploy" to <----+

(ASCII drawing done with

This isn't ideal, by any means, but it affords me a couple of benefits:

  • I can serve a non-Octopress index.html / CSS / etc., out of my home directory.
  • If I ever decide to serve anything else out of the site (other than an Octopress blog), it will be much easier to keep separate from the GH Pages Jekyll + Octopress auto-build, which happens any time the root directory is updated.
  • The built / 'deployed' blog code is separate from both my blog source and my primary website source. This is especially important, as it means that the Octopress 'rake deploy' script doesn't get to touch the rest of my website. A little OCD, yes, but it is nice having the increased control.

Obviously, it's not exactly the easiest setup to manage. It means publishing a blog post consists of:

  1. Write new post in my octoblog.git source tree.
  2. Run 'rake deploy' from within octoblog.git.
  3. Head to, do a quick "git remote update; git pull".
  4. 'cd' up one directory and "git ci -a; git push".

The normal setup requires just the first two steps. So, slightly more annoying, but it suits my needs.

It took a couple of days of working with GH Pages support to sort out everything that was wrong. Unfortunately, I discovered a couple of errors in documentation during the debug process - the hard way.

The fixes were pretty simple, though, once I discovered them. vs

When GitHub pages first started out, the former was the nomenclature for creating a repo that would serve a personal webpage. Now, it is the latter. According to this blog post from GitHub, if you have a site with the old name, you don't need to change it. The Octopress
actually doesn't reflect the change, at all, yet.

Unfortunately, according to the help I got from GitHub, neither of these are accurate:

Hi Ben,

The Octopress documentation is a little bit behind -- GitHub Pages now requires
a url structure of rather than .com. This should fix what
you're running into.

As a plus, you can now submit a pull request back to Octopress' core
documentation and get some open source karma :)


So, step 1 was changing '' to ''.

Serving Octopress out of a Subdirectory

After fixing the above issue, I was still getting the 'page build failed' error, and my root directory files still weren't getting updated properly. I responded to my friendly GH Pages customer service rep, who sent the following back:

Hi Ben,

It looks like I read your first email too quickly. It looks like your submodule
is causing the error. Our documentation of submodules in GitHub Pages is at Switching to the
read-only git url should fix things.

This explains why your index page isn't properly rendering -- fixing your
submodule should cause a successful build.


I had originally ignored the page referenced in the email, because it says the following:

Using submodules with Pages 
If your repository contains submodules, they will be
automatically pulled in when the pages are built.

Make sure you use the git:// read-only URL for your submodules. HTTPS and SSH
URLs will cause the build to fail with a "submodule fetch failed" error.

Submodules must also be served from public repositories; the Pages server cannot
access private repositories.

Note that the error is supposed to be 'submodule fetch failed' - which isn't what I was seeing. But, I went ahead and made the changes. I changed the URLs in:


With the following change:

-   url =
+   url = git://

...pushed the change... and viola! Everything is fixed!


Everything is working as expected now. It took a couple of days, and of course the changes were relatively minor. Unfortunately, the documentation source with the errors referenced above isn't stored on GitHub (at least not that I can find). Otherwise, a pull request would be in order =)

Ben Hilburn

Ben Hilburn

bits, nibbles, bytes, and words
D.C. Metro Area