I’ve always hosted my static site projects on GitHub Pages and honestly, it’s been great. Setup takes no time (maybe because I’ve done it so many times before), especially since GitHub simplified the publishing process. But because 🎶 I’m just a sucker for pain 🎶(insert music to Sucker for Pain from the Suicide Squad OST ), I decided to give GitLab Pages a try instead.

It’s not that GitLab Pages is bad, far from it. But doing anything for the first time (even setting up GitHub Pages) will be a little bit tricky. Also, GitLab Pages is slightly harder to setup but provides much more flexibility, so weigh your pros and cons. Jekyll is my static site generator of choice.

Types of sites

Similar to GitHub Pages, GitLab Pages also allows you to have a single user site and unlimited project sites. But what GitLab Pages has in addition is the concept of groups. If you haven’t used GitLab before, you can actually group several projects together into a directory, which provides a namespace under which all these projects are housed under. And you can then give an user access to all projects within that group. GitLab pages allows you to have a unique site per group as well.

General steps for user/group site

1. Create a repository on GitLab named YOUR_USER_NAME.gitlab.io, making sure the first part matches your user name or group name exactly.

2. Create a .gitlab-ci.yml file. This file controls the build process for your site. Every push to the Git repository will trigger the runner and you can check its progress on the /pipelines page of your project.

   

   Note: I wish I had found this page when I was setting up, but I somehow missed it. So I’m highlighting it to you now. Refer to Build Jekyll with Bundler if you’re using Jekyll as your static site generator.

3. For Jekyll sites, your gitlab-ci.yml will look something like this:

   # requiring the environment of Ruby 2.3.x
   image: ruby:2.3
   # add bundle cache to 'vendor' for speeding up builds
   cache:
     paths:
      - vendor/
   before_script:
            - bundle install --path vendor
   # the 'pages' job will deploy and build your site to the 'public' path
   pages:
     stage: deploy
     script:
      - bundle exec jekyll build -d public/
     artifacts:
        paths:
          - public
     only:
      - master # this job will affect only the 'master' branch

4. Make sure you exclude the vendor directory in your _config.yml file. This step tripped me up a bit (evidence can be seen in the first couple of my repository commits). If you, unlike me, are familiar with the YAML syntax, you probably wouldn’t have ran into the problems I did.

   First of all, I didn’t exclude the vendor directory in my initial commit, so I ran into an invalid date '0000-00-00' error and my pipeline failed. So after a bit of googling, I found this issue log and the solution was to exclude the vendor directory. But the instruction was to add the line exclude: [vendor] to the _config.yml file.

   With my complete lack of YAML knowledge, I dutifully added the line and the relevant portion of the _config.yml file looked like this:

   # Do NOT do this. This is WRONG!!
   exclude:
            - [vendor]
            - Gemfile
            - Gemfile.lock
            - node_modules
            - gulpfile.js
            - package.json

   Basically, I didn’t know the shorthand for lists in YAML was written like Javascript arrays. So here are the 2 correct ways to exclude multiple files/folders in your _config_yml.

   exclude:
            - vendor
            - Gemfile
            - Gemfile.lock
            - node_modules
            - gulpfile.js
            - package.json

   OR

   exclude: [vendor, "Gemfile", "Gemfile.lock", node_modules, "gulpfile.js", "package.json"]

5. Push your files up to GitLab and watch it run in the pipeline page. If you run into a Could not find a Javascript runtime. error, which I somehow did, you may need to include the line gem 'therubyracer' in your Gemfile. Relevant issue log here. Why is a Javascript runtime needed for a Jekyll site you may ask? It’s most probably not needed, but something up with my site’s files 🤷.

Wrapping up

It wasn’t a terrible experience, and the trip-ups were largely due to my own stupidity anyway. But at least I got the site up and running. Feel free to reference my site’s setup on GitLab. Also, because of the whole GitLab CI configuration thing, you’re free to use any static site generator of your choice, unlike GitHub Pages, which is slightly limiting. If you find GitHub Pages a bit too restrictive for your liking, why not give GitLab Pages a try?

GitLab Pages