Build and run your Blog or Website with GitLab Pages

As already mentioned in an older post I’m using GitLab Pages to host my “About me” website. In this story, I would like to give you some more technical insights on how to do this. I will use my own website as an example.

meisenzahl.org — based on Hugo, running on GitLab Pages

GitLab Pages allows you to run any website built by a static website generator. Hugo, Jekyll, Hexo or Pelican are only some examples. There are much more out there. In my case it’s Hugo.

So, first of all, you need a new GitLab project to commit your code and content. You then need to create a GitLab CI pipeline and configure your Pages settings. It's straightforward and documented here. Because of the good documentation, I will not talk about the default steps in this post. But would like to provide you with some tips and thoughts:

  • I would recommend using a private project. It doesn’t need to be a public one to serve a public site.
  • Exclude your artifacts (public folder when using Hugo) by adding the path into your .gitignore file. Otherwise, those files will be also committed to a project which can cause issues after testing your site locally. Using Docker to test your build locally would be even better.
  • Disable GitLab “Auto DevOps” and enable the shared runners which are needed to build your site.
  • Limit your pipeline to only run after a commit to the master branch. This will allow you to commit to any other branch without updating your production environment.

By using a build pipeline you will make sure that a new Docker image will be built after every commit. The new images will then be deployed without any downtime. This is the pipeline configuration (.gitlab-ci.yml) I’m using for meisenzahl.org:

image: monachus/hugo
variables:
GIT_SUBMODULE_STRATEGY: recursive
pages:
script:
- hugo
artifacts:
paths:
- public
only:
- master

Artifacts” defines the location of your website artifacts. “Only” can be used to limit the pipeline to a specific branch. In my case, the pipeline is only running after a commit to the master branch.

Last but not least you need to configure your domain and import your certificates in the GitLab Pages settings as well as update your DNS settings. This step is optional and only needed when you like to use a custom domain.