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(3).

The installation documentation for Pandoc also includes examples on using Pandoc within GitLab(4). The information therein will be incorporated into this process.

.gitlab-ci.yml

Global Settings

make is unfortuntately not already present in many common images and while it could be added to a new image easily enough I’m hoping to avoid the need to create and use a custom image solely for the transient need of building. While experimenting with docker run to test out some images I tried the gcc image figuring it would likely have make and it did, and then decided to scan through the most popular images on Docker Hub for a candidate(5). make is less standard than I would have guessed but knowing it’s a typical part of the toolchain in Go projects I zeroed in on that one and it worked. While both the golang and gcc images are larger than I’d like (though there may be slimmer tags available), the golang is smaller and hopefully more likely to make use of caches so I’ll go with that one pinned to one of the latest stable versions that includes make.

image: golang:1.16.6-buster

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

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

Generate Pandoc Commands

To make use of standard images rather than needing to creating a custom one, make will be invoked here to produce a shell script which will be published as an artifact to be used later.

gen-script:
  script:
    - make gen_site
  artifacts:
    paths:
      - gen_site

Pages

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

pages:
  stage: deploy

While no additional preparation is required, a script element is expected and therefore an effective no-op is added:

  script:
    - echo 'Nothing to do...'

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

  artifacts:
    paths:
      - public
1.
GitLab pages | GitLab [online]. 21 April 2021. Available from: https://docs.gitlab.com/ee/user/project/pages/
2.
GitLab pages integration with let’s encrypt | GitLab [online]. 13 August 2021. Available from: https://docs.gitlab.com/ee/user/project/pages/custom_domains_ssl_tls_certification/lets_encrypt_integration.html
3.
Keyword reference for the .gitlab-ci.yml file | GitLab #pages [online]. June 2021. Available from: https://docs.gitlab.com/ee/ci/yaml/README.html#pages
4.
Pandoc - installing pandoc [online]. 28 September 2021. Available from: https://pandoc.org/installing.html
5.
Explore docker’s container image registry | docker hub [online]. July 2021. Available from: https://hub.docker.com/search?type=image
6.
Create a GitLab pages website from scratch | GitLab [online]. 30 May 2021. Available from: https://docs.gitlab.com/ee/user/project/pages/getting_started/pages_from_scratch.html