Last week I decided to migrate this blog, Eight Portions, from GitHub Pages to GitLab Pages for hosting service. My experience to-date has been net positive: GitLab Pages offers more flexibility and control over your site than does GitHub Pages, though at the expense of performance and ease-of-use. This post offers a high-level comparison of these two hosting services, and provides a set of quick-start instructions and resources to get you started should you decide to follow suit.

Contents

To move or not to move: high-level considerations

I’ve outlined below the biggest factors that went into my decision to migrate to GitLab Pages. There are obviously many other factors to consider, which may or may not be important to you, so assess these in the context of your needs.

Advantages of GitLab Pages:

  • GitLab Pages allows your site to utilize any Jekyll plugin, while GitHub Pages only officially supports the plugins in the GitHub Pages gem.
  • GitLab Pages supports non-Jekyll static website generators such as Hugo and Hyde, while GitHub Pages requires you to push locally-built sites if using non-Jekyll static site generators
  • CI (Continuous Integration) is built into GitLab, whereas full CI functionality is not built into GitHub Pages1. Once configured, GitLab CI can automatically:
    • Test2 and build all of your branches with user-specified dependencies and versions
    • Publish your master branch build, and save your other branches’ builds for testing purposes
    • Notify you of any errors along the way3

Disadvantages of GitLab Pages:

  • Build time on GitLab Pages is slightly slower than on GitHub Pages, though I’m sure there are ways for users to significantly enhance their CI builds4
  • It is slightly more involved to get off the ground with GitLab Pages than with GitHub Pages, largely due to the CI configuration; hopefully the instructions below will help with this
  • GitLab Pages documentation isn’t as well-organized as the GitHub Pages documentation – again, I hope the instructions below will help you navigate the setup process

Other noticeable differences, less relevant to static site hosting:

  • GitLab offers free private repos (both GitLab and GitHub offer free public repos)
  • The GitLab platform is itself open source
  • The GitLab community is significantly smaller than the GitHub community

Instructions and additional resources

Should you choose to migrate to GitLab Pages like I did, start by simply cloning your existing Jekyll repo to GitLab.

Next, confirm that shared Runners are enabled (Settings > Runners), and then create a configuration file in your repo’s root directory named .gitlab-ci.yml to tell the CI how to test and build your site. This document provides a good template if you’re generating your site with Jekyll. If you’re going to using another static site generator, you can find some great examples here. This is what my config file looks like:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28

image: ruby:2.3  # Use Ruby Docker image

cache:  # Add Bundler cache to 'vendor' directory
  paths:
    - vendor/

before_script:  # Install Gems to 'vendor' directory
  - bundle install --path vendor

test:
  stage: test
  script:  # Generate test site(s) into 'test' directory
  - bundle exec jekyll build -d test
  artifacts:  # Save a zipped version for download
    paths:
    - test
  except:  # Execute for all branches except master
  - master

pages:
  stage: deploy
  script:  # Generate public site and deploy
  - bundle exec jekyll build -d public
  artifacts:  # Save a zipped version for download
    paths:
    - public
  only:  # Only deploy the master branch
  - master

Once your CI config file is set up, change your repo name to <GitLab_username>.gitlab.io. If you have a custom domain name, then you’ll need to:

  1. With your domain name registrar (e.g., Namecheap), drop your old A Record(s)5 and add a new one with the value of GitLab Pages’ IP: 52.167.214.135
  2. Update your CNAME Record with your domain name registrar to <GitLab_username>.gitlab.io
  3. Remove the CNAME text file from your previous repo

Next, you should strongly consider securing your site by adding HTTPS, using Let’s Encrypt and Certbot (it’s all free). This step is optional, though recommended – a nice summary from Google of why you should use HTTPS can be found here.

Lastly, add your domain to GitLab Pages (Settings > Pages), adding your new TLS certificate and key if relevant. Congrats – you’re all set up!

Additional resources

Footnotes

  1. GitHub Pages automatically generates your site from the latest master branch commit, but does not give the user the ability to automatically run their own tests, specify dependency versions, or build from non-master branches; it’s possible to use Travis-CI to get these features if hosting from GitHub Pages, though some additional work is required ↩

  2. Testing scripts might do some combination of the following: test jekyll build for build failures, test analysis or other code run at compile time, and/or validate HTML output (great summary here) ↩

  3. Build notifications can be enabled in your site’s GitLab repo by going to Settings > Services > Builds emails ↩

  4. Under my CI configuration GitLab CI takes 1-2 minutes to build my site, whereas it typically took GitHub Pages 10-20 seconds (this isn’t a huge negative for me) – part of this is due to the fact that I build all branches (not just master) and part is due to the fact that the GitLab Pages build process is containerized, so it requires time to load Docker images, Gems, etc.; I may look into Jekyll incremental builds if performance becomes too much of an issue ↩

  5. If you are currently using GitHub Pages, then you will likely have two A Records: 192.30.252.153 and 192.30.252.154 ↩