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
Create a repository on GitLab named
YOUR_USER_NAME.gitlab.io, making sure the first part matches your user name or group name exactly.
.gitlab-ci.ymlfile. 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
/pipelinespage 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.
For Jekyll sites, your
gitlab-ci.ymlwill 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
Make sure you exclude the
vendordirectory in your
_config.ymlfile. 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
vendordirectory 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
vendordirectory. But the instruction was to add the line
exclude: [vendor]to the
With my complete lack of YAML knowledge, I dutifully added the line and the relevant portion of the
_config.ymlfile looked like this:
# Do NOT do this. This is WRONG!! exclude: - [vendor] - Gemfile - Gemfile.lock - node_modules - gulpfile.js - package.json
exclude: - vendor - Gemfile - Gemfile.lock - node_modules - gulpfile.js - package.json
exclude: [vendor, "Gemfile", "Gemfile.lock", node_modules, "gulpfile.js", "package.json"]
Push your files up to GitLab and watch it run in the pipeline page. If you run into a
gem 'therubyracer'in your
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?