Circle CI + jekyll in github

Purpose

The reason why we need to cope with this is that github doesn’t support all jekyll plugins. Therefore when you upload jekyll projects with something like Jekyll assets tags, github would show build fail, and won’t create any page. To handle this problem, github recommends users to build static pages on other machines, and push them to the repository. The build script in chalk pushes static files in gh-page branch, and ask users to choose the shown branch in repository settings. Basically this is a good idea, but due to the bug in github (users cannot choose master or gh-page in settings when build fail), it cannot work anyway.

Solution

To deal with it, the only solution is to create another repository to hold the jekyll source, and use deploy script to push the built files to username.github.io. As being a lazy engineer, I prefer to do all the things with simple commits and pushes. The service I have chosen is Circle CI, but the basic concept and steps should be the same for others:

1. Create a new key for the repository you’re going to build on, and link it to the CI service you use. You could choose Circle CI from the list of services already integrated with github in repository settings.

2. Create a new key for the repository you’re going to deploy to, or directly use the user key to link to the CI project we have set in step 1. Notice you cannot use the same key created in step 1 since github forbids it. To add new keys in Circle CI please follow this link.

3. Create a circle.yml in your repository root. A simple example may look like:

   machine:
     ruby:
       version: 2.4.0
   
   dependencies:
     pre:
       - ./bin/prebuild_environment_script.sh
   
   test:
     post:
       - ./bin/build_and_deploy_script.sh
       - any thing else
   

   
   

4. In your ./bin/build_and_deploy_script.sh, you have to call jekyll build to create static htmls in _site directly, and push this folder to the target repository. Notice in step 2 we already imported custom keys, so we could ignore the passphase or any ssh configuration things in containers when using git push. One sample script may look like:

   #!/bin/bash
   bower install
   bundle exec jekyll build
   
   cd _site
   git init
   git remote add origin git@github.com:username/username.github.io.git
   
   git config user.email "user_email_address"
   git config user.name "username"
   git add -fA
   git commit --allow-empty -m "$(git log -1 --pretty=%B) [ci skip]"
   git push -f -q origin master
   
   cd ..
   rm -rf _site
   exit 0
   

   
   

5. Almost done. Just push your changes to your jekyll source repository and wait for the auto-build invokation in CI.