Posts /

Jekyll deployment automation with GitLab CI

Twitter Facebook Google+
11 May 2017

Disclaimer: I am not a web guy. This works for me, however non-optimal it may be

If you head over to this site’s public Git repo, you’ll see it uses GitLab CI for building. The way I have it set up is that any branch except master gets built as a test, and master gets built and deployed directly to my live site. Better get using those feature branches!

Here, I’ll show you how I set this up, and how you can do it for your own sites.

Level requirements

You’ll need a few things to get this up and running:

Getting GitLab Runner… running

Firstly, disable shared runners in your repo’s Settings > CI/CD Pipelines. This’ll force GitLab to use just our own server for these builds.

To do the building, we’ll be using a GitLab Runner directly on our webserver, in “specific” mode. That means the runner is only able to run builds from the repos we tell it to, so random people can’t start sending builds to our new runner. Just follow GitLab’s own instructions up to where you configure the runner.

When configuring the runner and being asked for a few different things, here’s what you want to enter:

Coordinator URL: https://gitlab.com/ci
Token: Find this by going to your repo on GitLab, then heading through Settings > CI/CD Pipelines. It'll be just under the "Specific Runners" heading
Description: Any description you like containing letters, numbers and hyphens. Example: eientei-webserver
Executor: shell

Don’t forget to (re)start the runner. As soon as you do that, refresh the CI/CD Pipelines page. You should see your new runner appear in the Specific Runners list. Just hit “Enable for this project”, and you’re good to go. You can also lock the runner to just this project, if you like.

Writing .gitlab-ci.yml

.gitlab-ci.yml is the file that tells GitLab what to build, how to build it and when to build it. It’s similar to Maven’s pom.xml (disclaimer: I’m not a Java dev, either). My own CI config is pretty straight-forward, so I’ll run you through that as a template. Note: you can always find the current version of my CI config here.

# Template .gitlab-ci.yml for https://circinusp.co.uk/blog/deploying-jekyll-with-gitlab-ci/
# Based on GitLab's own Jekyll CI template: https://gitlab.com/pages/jekyll
image: ruby:2.3

variables:
  JEKYLL_ENV: production

# Pipeline #1: Testing branches other than master build successfully
test:
  stage: test
  script:
  - bundle exec jekyll build -d test
  dependencies: []
  except:
  - master

# Pipeline #2: Building master to webroot
make-live:
  stage: deploy
  script:
  - bundle exec jekyll build -d /path/to/webroot # Change this!
  dependencies: []
  only:
  - master

That config will build all branches except from master, just to make sure they actually do build. You’ll get a failure and an email alert if you push broken code to a feature branch, for example. Assurance more than anything.

The second pipeline builds our site to our webroot whenever there’s a commit to master, automating the building and deployment process. Want to change something on your site? Just push to master. Ideally you’d make a feature branch and merge request, but you already know that.

Warning: When building, Jekyll first deletes everything in the target directory. Make sure nothing’s there that you don’t want to lose! Building into a subdirectory like “blog/” is a good idea

Done in time for tea

I’m British, what do you want with me? D:

And we’re essentially done! You’ll likely need to tweak the /path/to/webroot part of the make-live script to point to somewhere in your webroot, and you might also need to tweak the “bundle exec” part, especially if you aren’t using Bundler to run Jekyll.

One more thing, the first time your runner performs a build, it’ll likely fail. To fix this, head over to /home/gitlab-runner and find your way through the directories until you end up at the Git repo for your site. Run “bundler install” and any additional local setup needed for building your site for production. Then, go into the failed build’s log on GitLab and retry it. It should build this time. If not, read the log for clues.

Happy building!


Twitter Facebook Google+