Skip to main content

How to Test Gitlab CI Pipelines locally

· 2 min read
Stephan Hochdörfer

Testing GitLab CI build pipelines can be a bit annoying. You must make your changes, commit and push them to kick off the CI pipeline. Then you have to wait a while for the result to show up and start over again if something went wrong. If your CI runners are busy, you keep waiting and waiting for the next free slot. Luckily, it is possible to run GitLab CI jobs completely locally. After installing the gitlab-runner package locally, you can execute a job like this:

gitlab-runner exec shell my_job

This will run the “my_job” job from your .gitlab-ci.yaml file with the shell runner. Since in our setups we mostly use Docker containers, we have to test our jobs with the “docker” executor:

gitlab-runner exec docker my_job

This will then download the needed docker image, run it and execute all job commands within the docker container.
One downside of this: If you have CI variables configured in your GitLab project, you need to set them manually in the job as the local runner is not connected to your GitLab project and thus is not aware of those variables. The same applies to globally configured CI variables in your Runner configuration.