Things I Learned While Moving to Gitlab Pages

After spending a couple of weeks rebuilding this site with Github Pages, I discovered that Gitlab had a similar offering. Since I’ve been using Gitlab exclusively at work, I figured I should give that a shot instead. Moving the files wasn’t difficult, but I did discover that some things worked differently. I also learned that Gitlab Pages had more to offer.

Github Gets Straight to It

Github Pages is very simple to use.

• Personal or Project site.
• Push your own static content (HTML, JS, CSS, etc.)
• It only supports Jekyll for static site generation.
• Only whitelisted plugins for Jekyll are supported.
• You get one apex domain and one subdomain.
  • Apex: example.com
  • Subdomain: www.example.com or blog.example.com, but not both.
• Private repositories for public sites are not available with GitHub Free.

Gitlab is More Robust

Gitlab Pages is simple, until it’s not simple.

• Personal or Project site.
• Push your own static content (HTML, JS, CSS, etc.)
• Any static site generator (e.g. Jekyll, Hugo, Middleman, Harp, Hexo, and Brunch)
  • You can specify whichever plugins you need.
• Uses Gitlab CI/CD to build and publish the site.
• Allows multiple custom domains
• Private repositories for public sites are free.

Differences with Jekyll

There are some small, but significant differences with how Jekyll is configured between the two offerings.

Core Configuration

The biggest difference between the two offerings is related to configuring Jekyll plugins.

Github Pages configures plugins in the main _config.yml file.

# The release of Jekyll Now that you're using
version: v1.2.0
plugins:
  - jekyll-sitemap # Create a sitemap using the official Jekyll sitemap gem
  - jekyll-feed # Create an Atom feed using the official Jekyll feed gem
  - jekyll-redirect-from
  - jekyll-paginate

Gitlab Pages uses the main _config.yml file, along with a Gemfile to load plugins. Also notice that the Gemfile sets the value of Jekyll, as opposed to the version setting in _config.yml.

# _config.yml, uses gems instead of plugins
gems:
  - jekyll-sitemap # Create a sitemap using the official Jekyll sitemap gem
  - jekyll-feed # Create an Atom feed using the official Jekyll feed gem
  - jekyll-redirect-from
  - jekyll-paginate-v2

# Gemfile
# This will help ensure the proper Jekyll version is running.
gem "jekyll", "3.4.0"
gem 'jekyll-sitemap'
gem 'jekyll-feed'
gem 'jekyll-paginate-v2'
gem 'jekyll-redirect-from'

Plugins

With the newer version of Jekyll loaded by the Gemfile, I also needed to use a newer version of the pagination plugin.

Redirecting Old URLs

My old site ran a version of BlogCFC, which is a ColdFusion based software. The URLs generated by that application were in the standard blog post format:

/blog/index.cfm/2010/01/01/post-title/

Jekyll requires the jekyll-redirect-from plugin to redirect URLs. Note: You can redirect from external or internal URLs. This is very handy if you want to publish an update to an old post without changing its content or breaking links.

For Github Pages, the front matter at the top of a post file will redirect like this:

---
redirect_from: "/blog/index.cfm/2010/01/01/post-title"
---

This creates a static HTML file here: _site/blog/index.cfm/2010/01/01/post-title.html

Gitlab Pages uses a slightly different format:

---
redirect_from:
    - /blog/index.cfm/2010/01/01/post-title/
---

This creates a similar static HTML file here: _site/blog/index.cfm/2010/01/01/post-title/index.html

Both HTML files have the same content, basically a <meta http-equiv="refresh"> that redirects to file generated by Jekyll.

Gitlab CI/CD

GitLab Continuous Integration (CI) & Continuous Delivery (CD)

GitLab CI/CD pipelines build, test, deploy, and monitor your code as part of a single, integrated workflow

This might be a bit overkill for a simple blog, but if you’re working on a more robust static site, this can definitely come in handy.

Here’s the basic .gitlab-ci.yml file I use for this site. Gitlab will require one in order to deploy your site. IIRC, it can generate one for you as part of setting up the repository.

image: ruby:2.3

variables:
  JEKYLL_ENV: production

before_script:
  - bundle install

test:
  stage: test
  script:
  - bundle exec jekyll build -d test
  artifacts:
    paths:
    - test
  except:
  - master

pages:
  stage: deploy
  script:
  - bundle exec jekyll build -d public
  artifacts:
    paths:
    - public
  only:
  - master

A Few More Things

In an upcoming post (or two), I’ll go into how I redirected my old domain and links to this site. I’ll also cover how to generate free SSH certificates more easily than is outlined in the Gitlab docs.