Setup static website hosting with Gitlab pages


This article covers how to setup a static website (HTML/Jekyll) with Gitlab and Gitlab-CI. Gitlab is a git repository hosting solution and comes in two flavors: a community edition and an enterprise edition. What’s described in this article is supported by both flavors. Gitlab-CI is an addendum to Gitlab and may be used to setup pipelines and provide continuous integration for code deployments.


A high-level flow of what we are going to talk about in this article can be described with this schematic.

We are going to keep things simple and not worry about things like scalability at the moment. As such we will have all our components in one box. However, please note this is not ideal for a production environment.


We are going to start with setting the things we need up and move on to creating a test static website. The only prerequisite required for this tutorial is an installation of Gitlab community or enterprise edition. We are also going to work on an Ubuntu box. For other distros, while the conceptual basis of this article would remain unchanged, you may have to adjust some commands and settings.

Set up Docker

Setting up Docker is pretty straight forward and there are several articles on the Internet for it. As such I am going go over just the basics and leave everything that’s not relevant to this article out.

Add the GPG key for the Docker repository:

curl -fsSL | sudo apt-key add -

Add the Docker repository to the APT sources:

sudo add-apt-repository "deb [arch=amd64] $(lsb_release -cs) stable"

Update your package database:

sudo apt-get update

Install Docker:

sudo apt-get install -y docker-ce

This would install and start Docker up. For our example, we are going to install just one image: rails. At the time of writing this article, these were the available images.

sudo docker search rails
NAME                           DESCRIPTION                                     STARS     OFFICIAL   AUTOMATED
rails                          Rails is an open-source web application fr...   692       [OK]
bluebu/rails-alpine            rails-alpine with different ruby version, ...   6                    [OK]
asux/rails                     Docker base image: Rails + Puma                 5                    [OK]
dkubb/alpine-rails-nginx       An Alpine Linux container for Rails applic...   3                    [OK]
bitnami/rails                  Bitnami Ruby on Rails Docker Image              3                    [OK]
instedd/nginx-rails            nginx rails                                     3                    [OK]
toxix/debian-rails             Debian based Ruby on Rails incl. imagemagi...   2                    [OK]
newsdev/rails                  The base Ruby image with additions to supp...   2                    [OK]
tenstartups/rails                                                              2                    [OK]
zumbrunnen/rails               Ruby on Rails image, using Passenger Stand...   2                    [OK]
ledermann/docker-rails         Simple Rails application to demonstrate us...   1                    [OK]
citizensadvice/rails           The Citizens Advice Ruby on Rails base image    1                    [OK]
mainlxc/nginx-rails            nginx-rails                                     1                    [OK]
liulantao/rails                Docker/Rails develop environment.               1                    [OK]
opensnp/rails                                             1                    [OK]
inklusive/rails                Custom rails build                              0                    [OK]
noonarai/rails-new             for just running rails new                      0                    [OK]
justincampbell/rails-compile   Environment for compiling a Rails app (bun...   0                    [OK]
uniqrn/rails                   rails image bundled relating gems               0                    [OK]
fishisfast/rails               Fishisfast rails image with nginx to serve...   0                    [OK]
convox/rails                   Convox base image for Ruby on Rails             0                    [OK]
bitnami/che-rails              Bitnami Rails Docker Image for Eclipse Che      0                    [OK]
reqvu/rails                    Rails                                           0                    [OK]
krismichalski/docker-rails     Ready to use Docker image for running Ruby...   0                    [OK]
fredym/rails                   Rails Docker Image                              0                    [OK]

We are going to install the very first one.

sudo docker pull rails

Setup continuous integration

Assuming that you have a working installation of Gitlab, let’s go about setting up continuous integration with Gitlab and Gitlab-CI.

Install one or more runners

Gitlab-CI uses “runners” as workhorses for compiling code. Runners are primarily connector code that can pull code from a git repository and run a pre-defined set of commands on a pre-defined platform. For example, say we want to build a project containing Java code on git push. When we push code into a Gitlab repository and the repository contains a build file (Gitlab calls it .gitlab-ci.yml, it’s YAML and needs to be present in the root directory of the project), Gitlab would trigger Gitlab-CI to build the code which in turn would trigger one or more runners which in turn would call (say) a Docker container and build the code. Pretty simple, right. Now Gitlab has two flavors of runners: a single runner and a multi-runner. As the names suggest, a single runner can run only one build at a time whereas a multi-runner can fork other runners to run multiple builds in parallel. We are going to install the multi-runner.  Assuming we have the Gitlab repository in our APT sources,

sudo apt-get install gitlab-ci-multi-runner

Register a runner with Gitlab

Gitlab needs to know where all its runners are at. To register a runner with Gitlab:

gitlab-ci-multi-runner register
Running in system-mode.

Please enter the gitlab-ci coordinator URL (e.g.
Please enter the gitlab-ci token for this runner:

The first prompt is the URL to your Gitlab instance and the second is a unique token found at Admin > Overview > Runners, like so:

We need to do this every time we want to register a new runner. When one or more runners are registered, it will show up in Admin > Overview > Runners, like so:

We need to make sure our runner is setup as a shared runner. A shared runner may be used by any build in a Round-Robin fashion whereas specific runners need to be assigned to projects.

Setup Gitlab pages

Now that we have continuous integration set up, it’s time to set Gitlab pages up. Gitlab pages is enabled by default. All the setup we really need to do is provide a domain for our pages. Now there are several approaches to setting domains up with Gitlab pages. One may set up a custom domain for a group of repositories serving some pages or one may set up a wildcard sub-domain to serve any and all kind of pages from any and all kind of groups or one may point a custom domain to one repository of pages as well. For this article, we are going to create a wildcard sub-domain and point it to our installation of Gitlab pages. That will help us achieve get URL’s like <repo_group><repo_name>.

Setup a wildcard sub-domain

This is a simple one. We need to head over to our domain’s DNS settings and add an A record (for IPv4) or an AAAA record (for IPv6) or both. For IPv4, it would look something like:

A    *    Automatic

where the first column is the record name, the second column is the sub-domain alias, the third is the IP address and the fourth is the TTL.

Add the domain information to Gitlab config

Open up gitlab.rb, usually in /etc/gitlab and search for pages_external_url. Add your domain name there. For instance, say if our domain is and our wildcard character sub-domain is *, we need to add

Setup a project

We are going to setup a simple project with two file: a .gitlab-ci.yml and a index.html. Our build file (.gitlab-ci.yml) would tell Gitlab CI to deploy our HTML files to a public directory ready to be served to the World Wide Web, like so:

  stage: deploy
  - mkdir .public
  - cp -r * .public
  - mv .public public
    - public
  - master

And a index.html:

This is for

A git push would trigger a build which would pick up our runner. All pipeline builds are recorded under Pipelines like so:

You may click on the job number and the deploy stage to see the console log for the build, like so:

After the build succeeds, we need to go to Settings > Pages in our Project to get the URL to our Gitlab pages website, like so:

And that’s about it!