Locally testing Gitlab CI jobs

by Florian Maul |
Nov 15, 2018 |



In my Team we are now using Gitlab for over two and a half years with an on premise installation and Docker based CI runners. It is an integral part of every project setup to get the CI pipeline running as soon as the first source code is commited. A world without automated builds, tests and deployments now seems like a thing of the past as corded telephones.

Still — the toolchain can be improved. Gitlab CI may not be as flexible as other build systems but it is pretty easy to set up and works well enough for us. You have to build a gitlab-ci.yml  file in the root of your Git repository which defines the stages and jobs of your build pipeline, very similar as Travis CI defines the builds. It can be a bit challenging to get the syntax right or have a bash script run the build correctly. Even after having written many pipeline definitions, I usually need multiple check ins into the Git repository and thus multiple build pipeline runs to get everything right.


The local runner

Now I recently found out that it is quite easy to test the gitlab-ci.yml locally on your machine (with some limitations):

  • You can run one single job from the gitlab-ci.yml using the gitlab-runner.
  • First you have to install the gitlab-runner locally, e.g. by running:

brew install gitlab-runner


Then you can run..

gitlab-runner exec docker <jobname>


to execute on job of from your gitlab-ci.yml file.

  • This allow you to test build scripts, variables, docker image and services before you even commit or push the pipeline definition. The job runs on a docker container locally on your machine, the same way as it would on the build server.
  • You can also test a build of your local source code (has to be commited locally) before pushing it to the repository.


test build scripts

Caveats and notes

  • The YAML is validated for syntax errors
  • You can only execute a single job, not the whole pipeline.
  • Build artifacts are not stored
  • Caching works only partly. The /cache folder can be used by mounting a local folder like this:
mkdir -p /tmp/gitlabrunner
gitlab-runner exec docker --docker-volumes /tmp/gitlabrunner:/cache <jobname>

  • The build (in docker) is significantly slower as a local build on my Mac, i.e. it’s not a good idea to run every local build using this method. But it is fine for testing the build script.
  • If you only want to run the script without the docker environment you can use the shell executor which runs the build script on your local machine directly. This will only work if all the tools and environment variables are available:
gitlab-runner exec shell <jobname>

Try it out

I hope this post has given you some insight into the gitlab-runner exec command for you to try it out next time, when you have to build a slightly more complicated build script. You may actually be able to avoid the chain of failed builds…


Have we aroused your interest? Then please feel free to write to us.

Are you interested in future blog posts from the life sciences area? – Please follow us on our social media accounts.

LinkedIn     facebook     twitter



Submit a Comment

Your email address will not be published. Required fields are marked *