Site Publishing - Matt Whipple

This site is published using GitLab Pages(1). It makes use of my custom domain with TLS provided by the GitLab support for Let’s Encrypt(2). The Let’s Encrypt integration can apparently suffer from an occasional hiccup (which I just experienced) that can be resolved through a retry as documented in the troubleshooting section of the relevant GitLab docs(2, #troubleshooting).

The documentation for GitLab pages(1) is overall solid but it seems fairly example heavy which leaves the need for a fair amount of inference based on those examples, though the reference documentation seems fairly compehensive. The publishing itself is handled by a .gitlab-ci.yml file and is tied to a “specific job called pages” within that file(gitlab-yaml-pages?).

I’ve fortunately also recently spent a significant amount of time using GitLab for CI at work and have therefore become more comfortable (and hopefully have landed on some appropriate practices).

In previous incarnations I seem to have been overly biased towards particular ways to use containers that don’t map onto CI servers and was therefore making some of the concerns here needlessly complicated. This is something I’ll likely revisit later.


The GitLab provided reference documentation(3) serves a fairly complete guide for options that can be used within this file.


Publishing should only be done for the primary branch so a workflow will be configured to target branches (4).

    - if: '$CI_COMMIT_BRANCH == "master"'


The special pages job is defined which should be run during the deploy stage (4).

  stage: deploy

Pandoc provides an image which acts as a solid starting point. The image typically calls pandoc as the entrypoint but this workflow is going to use make instead so the entrypoint needs to be overridden.

Additionally the GitLab will invoke things using its custom gitlab-runner which can cause issues if a shell is explicitly provided as an argument, and so an empty entrypoint is preferred here.

    name: pandoc/core:2.17.1-alpine
    entrypoint: [""]

Install make

make is not included by default in the pandoc image and so can be installed in a before_script definition.

    - apk add --no-cache make

Build site

Invoke the make target to produce the generated site.

    - make site

The (already existing) public directory will be published as an artifact:

      - public
GitLab pages | GitLab [online]. 21 April 2021. Available from:
GitLab pages integration with let’s encrypt | GitLab [online]. 13 August 2021. Available from:
Keyword reference for the ‘.gitlab-ci.yml‘ file | GitLab [online]. 4 March 2022. Available from:
Create a GitLab pages website from scratch | GitLab [online]. 30 May 2021. Available from: