How to Test Gitlab CI Pipelines locally in 2025

Three years ago I wrote a post about how to test GitLab CI pipelines locally. Unfortunately, GitLab discontinued this feature some time back as part of the Runner application's refactoring process.

I was looking for an alternative for a while and recently stumbled upon the firecow/gitlab-ci-local GitHub project, which solves this problem and allows running GitLab CI pipelines locally, either via the shell executor or the Docker executor.

If you are using a Debian-based distro, the installation process is pretty straightforward:

curl -s "https://gitlab-ci-local-ppa.firecow.dk/pubkey.gpg" | sudo apt-key add -
echo "deb https://gitlab-ci-local-ppa.firecow.dk ./" | sudo tee /etc/apt/sources.list.d/gitlab-ci-local.list

sudo apt-get update
sudo apt-get install gitlab-ci-local

If you are not using a Debian-based distro, you can also install the tool via npm, brew, or Git bash on Windows.

To run a job build:php, run gitlab-ci-local "build:php".

Thanks to the --variable parameter, you can also set build variables if needed. The command line parameters --network and --volume allow you to add other Docker networks or volumes to your build job, just in case you need external dependencies.

I've been using the tool for a few weeks now, and it does what it is supposed to. If you need to debug your GitLab CI pipeline, this seems to be a worthy tool for your toolbelt.