Technically Feasible

Gitlab CI from Scratch

Likeness of Michael Oldroyd
Michael Oldroyd

I only recently discovered how useful Gitlab CI is. Gitlab is an open source Github competitor. I've used it quite a lot over the years. After signing up for a gitlab.com account, you gain access to 2000 free build minutes per month for private projects. You can also run your own private CI runner if you are so inclined.

Creating a Basic CI Build

We're going to configure Gitlab to create our Eleventy static site, and deploy it to Gitlab pages. Create a .gitlab-ci.yml[1] file in the project's root.

image: "node:12"

before_script:
- npm install

site:
script:
- npx eleventy
artifacts:
paths:
- _site

This will instruct the CI runner to obtain the latest node 12 docker image. before_script is a setup stage to run before all other tasks — in this case we are runing npm install, after which the steps in the site task will execute. artifacts defines a path which will be persisted from the build result, and can be downloaded from the UI.

Deploying to Gitlab Pages

The build process now includes the command to build eleventy. That was easy 😃. If all you need is to build the artifact, then you are done. Our stated goal is deployment to Gitlab Pages, so we have a little more work to do. You will need to enable pages for your project.

image: "node:12"

before_script:
- npm install

pages:
stage: deploy
environment:
name: production
url: https://oldr.uk
script:
- npx eleventy --output=public
cache:
paths:
- node_modules/
artifacts:
paths:
- public
only:
- master

There is quite a lot going on here.

We have changed our build task to pages, which is specifically used by Gitlab Pages. We have updated the output directory to be public, because pages requires it. Eleventy output directory is easily configurable using --output=public, and we can then just change the artifact directory to public.

Resource Caching

cache:
    paths:
      - node_modules/

We have also enabled caching. This aims to reduce the build time, as the node_modules folder will be loaded from previous builds—and updated if necessary—and re-cached after a successful build.

Pipeline filter

only:
    - master

You can define one of more branches for which the pipeline task will execute. Our build will only run if the change was committed to the master branch.

Bring Your Own Domain

environment:
    name: production
    url: https://oldr.uk

Finally, we can configure Gitlab pages to work with your own domain, supporting TLS. You will need to configure your domain in the CI script; You will also need to configure your DNS records for your domain.

Have fun!


  1. Whats a yaml? ↩︎

Image of me

Michael Oldroyd

Michael is a Software Engineer working in the North West of England. Michael spends his days building hand-crafted PHP applications. Rumours of his super-hero status are currently unconfirmed. He savours his victories when solving difficult programming challenges; occasionally writing about them here, on his personal blog.