Gitlab Pages

Today I worked with Gitlab Pages. Also boy what a day to log the process because what seemed like a simple copy paste of a gitlab-ci.yml turned into all kinds of trouble shooting.

It all started by looking at the example pages/hugo to see what was necessary in order to build and publish this log on Gitlab Pages. Seemed simple enough, essentially a container with hugo installed that runs a special pages job with the public folder as the artifact.

Unfortunately a copy, paste, commit, push later and… nothing. The pipeline ran successfully but no site was published, and no url appeared under settings > pages. A bit of investigation and turns out this is expected. The pages settings page won’t show up until gitlab-ci.yml is committed on master.

After overcoming this hurdle, everything seems to run and I get a url in the settings but going to the page gave a big 404. At this point I regrouped and tried just forking the existing example to see how that worked. Sure enough it works like a charm. While digging into the config.toml in the example I keyed into a few things to try, namely the canonifyURLs setting and adding a trailing slash to the baseURL. Neither of which worked.

A break came when I realized I had not specified a theme in the hugo configuration. With all my work yesterday testing different configurations, I was always invoking the local testing server like hugo server -t hugo-lithium-theme. On the CI runner without this set hugo happily completes successfully but only .xml files are generated, which results in a 404 when visiting the site.

With this realization that I needed to set the theme I was close, but not quite across the finish line. I also realized that I currently have the theme included as a git submodule which was not being checked out. After reading the documentation I tried, tried, again and BAM I seemed to run into issue #2148.

fatal: unable to access
'https://github.com/jrutheiser/hugo-lithium-theme.git/': SSL certificate
problem: unable to get local issuer certificate

Fortunately @lesque came to the rescue with the work around of setting GIT_SSL_CAPATH=/etc/ssl/certs/. I made this change in my gitlab-ci.yml and we were finally in business! For what it’s worth, the other fix of using a before_script didn’t work because the build container didn’t have git installed. I wonder what system is performing the clone and how it is injecting the code into the container. Probably the gitlab ci-runner, and I could look it up to confirm since it’s all open source! I’ll leave that for another day.

Now the site was showing up, but the CSS was missing. Back to having a trailing slash on the hugo baseURL and all was live and looking good.

Great learning. The commits have been squashed to preserve the innocent.