Debug Gitlab Pages Build Locally

This post provides a step-by-step guide of how to debug gitlab pages build locally.
Categories:
Tags:

Gitlab pages is an awesome tool, which allows you to publish any static website to the internet.

One of the biggest frustration I had is that I don’t know whether a commit is breaking the build before submitting the changes for CI. I was wishing for a local mode for running the CI job.

Luckily there is. It takes a few steps, like summarized in the following sections.

Step 1: Download Gitlab Runner

Before anything, let’s set your arch environment variable. If you are using amd64, do it like this

export arch=amd64

Then, go to a download folder, and then download the gitlab runner image

For Ubuntu or Debian

# Replace ${arch} with any of the supported architectures, e.g. amd64, arm, arm64
# A full list of architectures can be found here https://gitlab-runner-downloads.s3.amazonaws.com/latest/index.html
curl -LJO "https://gitlab-runner-downloads.s3.amazonaws.com/latest/deb/gitlab-runner_${arch}.deb"

For CentOS or Red Hat Enterprise Linux

# Replace ${arch} with any of the supported architectures, e.g. amd64, arm, arm64
# A full list of architectures can be found here https://gitlab-runner-downloads.s3.amazonaws.com/latest/index.html
curl -LJO "https://gitlab-runner-downloads.s3.amazonaws.com/latest/rpm/gitlab-runner_${arch}.rpm"

Step 2: Install Gitlab Runner

To install gitlab runner on Ubuntu or Debian,

sudo dpkg -i "gitlab-runner_$arch.deb"

To install gitlab runner on CentOS or Red Hat Enterprise Linux

sudo rpm -i "gitlab-runner_$arch.rpm"

Step 3: Register Your Runner

Next, let’s register your runner. To register your runner, you’ll first need to acquire a token from gitlab. Go to your project, and then Settings -> CD/CD -> Runner -> Project Runners. You’ll see something like this

gitlab project runner

Grab the registration token, and run the following command

sudo gitlab-runner register --url https://gitlab.com/ --registration-token $REGISTRATION_TOKEN
  • The executor I selected is docker+machine, because I found it is used in the gitlab CI.
  • The docker image I used is the hugo image registry.gitlab.com/pages/hugo/hugo_extended:latest.

Step 4: Run Build Job Locally

Once you have finish the previous step, use the following command to run your job locally

gitlab-runner exec docker <job-name>

The job-name is defined in your .gitlab-ci.yml file. For me, the real command to run is:

gitlab-runner exec docker pages