How to use a CI (CodeShip) to deploy a theme that won't build on Github pages
Photo by Josh Sorenson

How to use a CI (CodeShip) to deploy a theme that won't build on Github pages

Github pages is a nice and free way to host a web site with static pages. It also supports Jekyll themes, which is great when you want to make things easier to edit and post.

Github pages has a bunch of themes ready to be used and they also support any Jekyll theme hosted on a public repository on github.com. You just have to use remote_theme instead of theme in the __config.yml file.

However, sometimes the theme that you have chosen builds without errors locally but doesn’t build when Github tries to do it. And then the error message is everything but helpful.

Locally you get this:

$ bundle exec jekyll doctor --config _config.yml
Configuration file: _config.yml
  Your test results are in. Everything looks fine.

And when Github builds it, you get this:

The page build failed for the master branch with the following error:

Page build failed. For more information, see https://help.github.com/en/articles/troubleshooting-github-pages-builds.

As you can see Page build failed. is not very useful. After hours trying to find the potential errors that they mention in the troubleshooting page, I gave up and went for a different solution.

The solution is to use a second repository (in my case: ldom-src) to host the source files with the theme. These are the files you were putting on the original repository for the github pages (in my case: ldom). Then setup a CI server (Continuous Integration) to build the static files every time you push to the -src repository and push the static file to the github pages repository.

Of course, you can put together the CI server yourself, using Jenkins for example, but it’s easier when you don’t have to manage a server for that. CodeShip is a CI service (I have no affiliation with them) that offers a free account limited to 100 builds per month (which is plenty for a personal site that you’ll update 30 times max per month).

Here is how you set it up and the scripts to use:

  1. Go to https://codeship.com
  2. Sign up for the free tier.
  3. Create a new project.

In the Setup Commands tab, select “I want to create my own custom commands” and use:

1
2
bundle install
bundle exec jekyll build --config _config.yml

In the Setup Commands text area, use:

1
2
3
4
5
6
7
8
9
10
11
12
REMOTE_REPOSITORY=${REMOTE_REPOSITORY:?'You need to configure the REMOTE_REPOSITORY environment variable!'}
REMOTE_BRANCH=${REMOTE_BRANCH:?'You need to configure the REMOTE_BRANCH environment variable!'}
set -e
git config --global user.email "<your email>"
git config --global user.name "<your name> (codeship)"
git clone ${REMOTE_REPOSITORY} _tmp -b ${REMOTE_BRANCH}
cp -R _site/* _tmp/
cd _tmp
git add .
git status
git commit -m "new build"
git push origin master

In the Environment tab, create 2 environment variables (to be used in the script above):

  • REMOTE_REPOSITORY: put the address of the destination repository, the one for the static Github pages, eg. git@github.com:ldom/ldom.git
  • REMOTE_BRANCH: put master
  1. The last step is to configure CodeShip and Github to allow the deploy script to push (write) to the destination repository.

This is described on this page: https://documentation.codeship.com/basic/builds-and-configuration/access-to-other-repositories/#sts=The%20Machine%20User%20Solution

I recommend using the “Machine User” solution. It involves:

  • creating a new github.com user and
  • give it access to the destination repository (by inviting it as a collaborator in the destination repository),
  • then you have to remove the key from the Deploy section under the destination repository (not your user settings, but the repository settings).
  • At last, you need to put that key (that has to be copied from General tab of the Project Settings in CodeShip) as a new key on the “Machine User” github account. (Note that if you don’t remove it first from the Deploy settings of the destination repository, you won’t be able to add that key to the “Machine User” keys).

Once all of this is done, you’ll enjoy a full automated (and free) system where you just have to push to the -src repository for everything to be built and deployed to Github pages!

Written by Ldom //