Introduce how to setup Jekyll website on GitLab Pages.

1. GitLab Pages

GitLab Pages are very similar to GitHub Pages. GitLab Pages also supports custom domain names and SSL certificates and includes a continuous integration platform. GitLab Pages supports static websites and builds any Static Site Generator (SSG), such as Jekyll, Hugo, Hexo, Middleman and Pelican.

There are two ways of getting started with GitLab Pages: either fork an existing project, or create a new one. In this posting, I will introduce how to migrate my personal Jekyll website from GitHub to GitLab.

2. Fork GitLab Pages Examples

2.1 Fork Existing Jekyll Project

Fork the repository After fork, you will see a new project in the list. image

2.2 Remove the Fork Relationship

Go to Settings > General, scroll down and expand ‘Advance’ and click the “Remove fork relationship” button. image

2.3 Trigger Build

Edit any file to trigger a build. For example, edit file ‘’. image Stage and Commit the change. image Then merge the request. image The pipeline is started automatically to trigger a new build. image After build is finished, merge the change. image The pipeline starts running again. image This time, the project is built and deployed. image

2.4 Test Page

Go to Settings->Page, the website url hosted in GitLab Pages appears, click on it. image We can see the Jekyll site. image

2.5 Change Domain

Notice the URL of the site is We can change it to other domains, for example,

Go to Settings > General, put the domain name and click “Change path” button. image Go to Settings->Page, the url is updated. image Click the url and you will see the site is in new domain(Please wait for few minutes if you don’t see it immediately). However, there is something wrong here, the page doesn’t look good. This is because the main.css file is not linked properly. image We are able to see the cause with chrome debugger. image To solve the issue, edit _config.yml, set baseurl to empty string. Submit and merge the request. image After the site is successfully built and deployed, we can access it with the new domain. image

3. Migrate Existing Site

3.1 Copy Files

Clone the project from to local, remove all existing files and copy all of the files from github repository into this folder.

Some configuration files need to be updated.

  • Gemfile
  • .gitlab-ci.yml

3.2 Gemfile

source ""

# This will help ensure the proper Jekyll version is running.
gem "jekyll", "3.8.5"

# Windows does not include zoneinfo files, so bundle the tzinfo-data gem
gem 'tzinfo-data', platforms: [:mingw, :mswin, :x64_mingw, :jruby]

gem "jekyll-seo-tag"

3.3 .gitlab-ci.yml

image: ruby:2.6

  JEKYLL_ENV: production

  - bundle install

  stage: test
  - bundle exec jekyll build -d test
    - test
  - master

  stage: deploy
  - bundle exec jekyll build -d public
    - public
  - master
  • public is the default folder for GitLab Pages.

3.4 Test

Test locally
Start Jekyll with command ‘bundle exec jekyll serve’.

$ bundle exec jekyll serve
Configuration file: /Users/Johnny/GitLab/
            Source: /Users/Johnny/GitLab/
       Destination: /Users/Johnny/GitLab/
 Incremental build: disabled. Enable with --incremental
                    done in 31.496 seconds.
 Auto-regeneration: enabled for '/Users/Johnny/GitLab/'
    Server address:
  Server running... press ctrl-c to stop.

Access or http://localhost:4000. image Test on GitLab
Push the changes to gitlab. After the site is successfully compiled and deployed, we are able to access it. The migration is done. image

There is a limitation of GitLab Pages, each size can’t be larger than 1GB. My website has lots of images, now it can’t be deployed due to the ‘too large’ error.

ERROR: Uploading artifacts to coordinator... too large archive  id=301083722 responseStatus=413 Request Entity Too Large status=413 Request Entity Too Large token=GqZyjRGe
FATAL: too large                                   
ERROR: Job failed: exit code 1


4. References