Running GitLab CI Jobs Locally

Sunday. April 27, 2025 - 2 mins

Guide: Running GitLab CI Jobs Locally

1. Introduction

Testing code before deploying is critical. GitLab CI/CD usually runs jobs on remote servers, but it’s often useful to execute them locally during development. As a Gitlab User/Learner I was looking for a simple way to etst my CI (gitlab-ci.yaml) without pushing any code to to repository. This guide shows how to run GitLab CI pipelines on your own machine. —

2. Method 1: Using `gitlab-ci-local`

2.1 Install

Check here if You want to install to other OS : gitlab-ci-local

Example .gitlab-ci.yml:

unit_test:
  image: python:latest
  script:
    - echo "running tests locally..."

Install gitlab-ci-local (Linux example):

sudo wget -O /etc/apt/sources.list.d/gitlab-ci-local.sources https://gitlab-ci-local-ppa.firecow.dk/gitlab-ci-local.sources
sudo apt-get update
sudo apt-get install gitlab-ci-local

Verify installation:

gitlab-ci-local --version

2.2 List Available Jobs

Navigate to your project directory:

cd demo
gitlab-ci-local --list

You should see:

unit_test

2.3 Run a Job

Execute the job:

gitlab-ci-local unit_test

Successful output confirms the job ran properly.

3. Method 2: Using GitLab Emulator (`gle`)

3.1 Install

Clone and install:

git clone https://gitlab.com/cunity/gitlab-emulator.git
cd gitlab-emulator
./install-venv.sh
source ~/.gle/venv/bin/activate

Check version:

gle --version

3.2 List and Run Jobs

Switch to project folder:

cd demo
gle --list

Run a specific job:

gle unit_test

You will see logs indicating successful execution inside a Docker container.

4. Method 3: Using GitLab Runner (Deprecated)

4.1 Install (Specific Version)

This feature deprecated with newer gitlab versions : https://gitlab.com/gitlab-org/gitlab/-/issues/385235

Download GitLab Runner 13.3.0:

sudo curl --output /usr/local/bin/gitlab-runner https://gitlab-runner-downloads.s3.amazonaws.com/v13.3.0/binaries/gitlab-runner-darwin-amd64
chmod +x /usr/local/bin/gitlab-runner

Confirm version:

gitlab-runner --version | grep Version

4.2 Run the Job

Execute using Docker:

gitlab-runner exec docker unit_test

The runner will pull the image, prepare the environment, and execute your test script.

5. Conclusion

In this guide, we demonstrated three different ways to run GitLab CI pipelines locally:

gitlab-ci-local for fast lightweight runs
GitLab Emulator (gle) for realistic simulations
GitLab Runner (older version) for authentic environment tests

Running CI jobs locally can greatly speed up development and improve the quality of your software.

Thanks for reading!

—

Guneycan Sanli

Guneycan Sanli

A person who like learning, music, travelling and sports.