Publishing in GitLab Pages

Here, I’m going to use GitLab Pages for hosting a website made from a Jekyll template I downloaded (al-folio)¹.

GitLab Pages is not only a host for static websites. The Continuous Integration and Delivery (CI/CD) pipelines allow you to run a Static Site Generator (SSG) to build the final web code when it is committed to its GitLab repository. So, in principle, the website update can be done from any computer with Git by just cloning, editing the content, committing and pushing. Then, the pipeline will compile the site on the GitLab servers and update the files. The GitLab Pages documentation provides a general overview of the features and configuration.

Infrastructure

Several systems are working together when building and deploying the website.

First, the website is built using a Jekyll template. Jekyll is the SSG that processes the content provided in Markdown files to fill in the space in a template, which is al-folio, in this case. Jekyll is a Ruby program, so an interpreter is needed. Ruby uses a Gemfile, which describes the dependencies (Gems) of a program (Jekyll) and defines where to look for them (RubyGems server). In addition, Ruby uses another program called Bundler to keep track of the dependencies of different programs, providing the correct version to each of them. That is what you need for the web design side.

On the other hand, GitLab runs its pipeline on a Docker image, which is executed every time you commit to the project. A YAML file called .gitlab-ci.yml configures the CI/CD pipeline, specifying which images should be loaded in the Docker container and what programs it has to run. So, we need to load Ruby, install Bundler and run Jekyll’s build procedure. Docker is a parallel universe from which I know only its general concepts, and I cannot discuss them in detail.

Building the content

As mentioned, the site style is defined by the template. I modified it to have an initial page different from the about me that is used by default, and I also changed some text here and there. The content is written in Markdown. At this point, I created an initial page, the blog, projects and bookmarks. I did all this locally, testing the results with the Jekyll server.

Creating the Gitlab Project

The website will be published as a user website, so the site address will be https://username.gitlab.io ². On the repository, user websites should use a project named as the URL, in this case username.gitlab.io.

1. Create an empty project with the name username.gitlab.io.
2. Create a simple web page to set up Pages. To do this, add to the project the files index.html, .gitlab-ci.yml and Gemfile, as explained here. You can do that directly in the Web IDE.
3. Commit the project. The pipeline should start automatically (because of the .gitlab-ci.yml file). If not, create a new pipeline. When finished, the web page should be visible at https://username.gitlab.io.

Another way to create the project is to push a local repository with the correct name and manually start the pipeline. For now, I use these three extra steps because they help make the process more transparent and easier to debug in case something fails.

Upload your website

Before uploading the local files, it is necessary to check the URL address set in the Jekyll configuration file _config.yml. There are two options to change: url and baseurl.

For user websites:

url: https://username.gitlab.io
baseurl:

Jekyll concatenates both options to form the final URL. In my case, the site is built directly in the root url, so the address of index.html is https://username.gitlab.io/index.html. The option baseurl is blank because of the same reason.

A different story happens with project websites. In that case, the address structure depends on the state of the Use unique domain option in the Pages settings. The table below shows the root url generated by GitLab and the baseurl that completes the website address.

Table 1: GitLab Pages URLs

Another point to pay attention to is the content of the .gitignore file. When working on the local repository, Jekyll creates the resulting website files and caches, which are unnecessary to track. An example of .gitignore for Jekyll looks as follows:

_site/
*-cache/
.jekyll-metadata
*.lock
.bundle/
vendor/
.env/
bin/

After these changes are done, we can upload the website.

1. Clone the username.gitlab.io project to your local computer.
2. Delete the old index.html file.
3. Copy the local website files into the project folder.
4. Commit and push. The pipeline will run again.

Check results

The website will be available in the URL https://username.gitlab.io.

When I first uploaded the site, I made a mistake in setting the url and baseurl options. The result was that only the home page was found and shown without formatting. The solution was to use the correct values for these options according to the abovementioned rules.

Final thoughts

The process described above seems quite cumbersome compared with the simple web pages based on HTML and an Apache web server I used to build a long time ago. And the first time you create the website, yes, it is unclear how to coordinate all the systems involved. But in practice, maintaining the content is much easier and quick. The temples you can find for free are impressively advanced and well-designed in a way that lets you focus on the content, which today is more interesting for us. I also appreciate the flexibility and seamless integration the CI/CD pipelines provide. Anyone can do today what was reserved for professionals ten years ago.