About | Blog

Debugging Gitlab CI's jobs locally

20 Jul 2020

Gitlab Runner to the rescue

Among all the CI/CD systems I've used so far, my favorite remains Circle CI. The documentation is simple, clear and you can SSH directly on the containers, which is priceless when you want to test or debug your build.

That being said, I use Gitlab CI for most of my personal projects. It's very powerful, but I find the documentation complex and not well organized. I came across the Gitlab Runner, the tool that'll interest us today, by looking at something completely different.

The Gitlab Runner is the tool used to launch our builds on Gitlab CI. It's open source and can be installed locally to test or debug your .gitlab-ci.yml configuration file. Yeah, you'll save precious time ✌️


The installation process is super simple. For Debian like distros, you have to add a special repository and then install the package gitlab-runner.

Let's run the job locally!

To debug your job with Gitlab Runner, you must first commit your changes. Indeed, your repository will be cloned into a builds/... repository, as it would be done by Gitlab CI.

I wanted to debug the deploy job of my configuration that was failing because of an erroneous SSH configuration. The command gitlab-runner exec docker deploy is here for that:

There are a few things to know about Gitlab Runner tho.

If like me you like to use YAML anchors as some kind of "functions", you'll have a problem as Gitlab Runner doesn't handle them locally. The error message FATAL: unsupported script is not really explicit... Just remove the anchors temporarily the time of your debug. Of course and fortunately it works perfectly on Gitlab CI.

If your job uses environment variables, you can pass them to Gitlab Runner via gitlab-runner exec docker --env VAR1=foo --env VAR2=bar deploy.

That's it, your job runs locally now 🙂 It's not as handy as being able to SSH on the container, but it's much better than nothing.