Run GitLab CI Pipelines Locally

4.71.0 · active · verified Sun Apr 19

gitlab-ci-local is a Node.js-based command-line interface (CLI) tool designed to execute GitLab CI/CD pipelines directly on a local machine. It aims to eliminate the need for frequent pushes to a remote GitLab server for testing `.gitlab-ci.yml` configurations. The current stable version is 4.71.0, with a rapid release cadence, often seeing multiple patch and minor versions per month addressing fixes and minor features. Its core differentiator is the ability to emulate GitLab's shell and Docker executors, enabling developers to validate their CI logic, environments, and artifacts without committing and pushing, thereby streamlining the development feedback loop and replacing custom dev-specific build scripts.

Common errors

```
'gitlab-ci-local' is not recognized as an internal or external command, operable program or batch file.
```
cause The `gitlab-ci-local` executable is not found in your system's PATH, typically because it wasn't installed globally or `npx` isn't being used.

fix Install globally via `npm install -g gitlab-ci-local` or execute using `npx gitlab-ci-local <command>`.
```
Error: Cannot connect to the Docker daemon at unix:///var/run/docker.sock. Is the docker daemon running?
```
cause gitlab-ci-local relies on a running Docker daemon for jobs configured to use the Docker executor. This error indicates Docker is not running or accessible.

fix Start Docker Desktop or the Docker daemon on your system. Ensure your user account has the necessary permissions to communicate with the Docker socket (e.g., by being in the `docker` group on Linux).
```
Job 'my-job' not found or cannot be selected.
```
cause The specified job name does not exist in your `.gitlab-ci.yml` file, or the job's `rules:`/`needs:` configuration prevents its selection in the current context.

fix Verify the job name in `.gitlab-ci.yml`. Check any `rules:` that might prevent the job from being selected. Use `gitlab-ci-local --list` to see all available jobs that can be run.
```
Error: .env autoload in compiled binaries disabled. Please specify with --dotenv-file option.
```
cause Automatic `.env` file loading is explicitly disabled in compiled binaries or when certain package managers like Bun are used, to prevent unexpected behavior.

fix Explicitly provide your `.env` file using the `--dotenv-file <path/to/.env>` CLI option, or define environment variables directly in your shell or using the `GCL_VARIABLE_` prefix.

Warnings

breaking In version 4.70.0, the mechanism for parsing custom environment variables was updated to use `GCL_VARIABLE_<name>`, replacing the deprecated `yargs .env("GCL")` pattern. Users relying on the old `yargs` based environment variable handling for specific `GCL` prefixes may need to update their configurations to the new `GCL_VARIABLE_` syntax.
Fix: Migrate environment variable definitions from `yargs .env("GCL")` styles to the new `GCL_VARIABLE_MY_VAR=value` format.
gotcha gitlab-ci-local primarily operates on *tracked* Git files. Untracked or uncommitted changes in your working directory might not be included in the job execution context, leading to discrepancies between local runs and remote GitLab pipelines.
Fix: Always stage and commit relevant changes before running `gitlab-ci-local` to ensure all intended files are part of the execution context. Consult the documentation for potential workarounds if untracked files must be included.
gotcha Windows users might encounter startup errors related to internal `id -u` commands failing. This was specifically addressed and fixed in version 4.71.0. Older versions on Windows may be unstable.
Fix: Upgrade to `gitlab-ci-local` version 4.71.0 or newer when running on Windows to ensure compatibility and stability. Use `npm install -g gitlab-ci-local@latest`.
gotcha Automatic `.env` file loading can be inconsistent. It was disabled in compiled binaries (since v4.69.0) and specifically for Bun's automatic `.env` loading (since v4.68.1). This means environment variables from `.env` files might not be picked up as expected without explicit configuration.
Fix: Explicitly pass environment variables via the CLI (e.g., `MY_VAR=value gitlab-ci-local job`) or ensure they are properly configured within your shell environment or by using the `GCL_VARIABLE_` prefix for specific variables.
gotcha Service aliases in Docker-based jobs were not correctly stripping ports and digests prior to version 4.70.1, which could lead to incorrect service resolution or connection failures.
Fix: Upgrade to `gitlab-ci-local` version 4.70.1 or newer if you are using services in your `.gitlab-ci.yml` and experiencing connectivity issues.

Install

npm install gitlab-ci-local npm
yarn add gitlab-ci-local yarn
pnpm add gitlab-ci-local pnpm

Quickstart

Demonstrates global installation, listing available CI jobs, and running a specific job with environment variables.

npm install -g gitlab-ci-local
# Navigate to your GitLab project directory
cd my-gitlab-project
# List all available jobs in your .gitlab-ci.yml
gitlab-ci-local --list

# Run a specific job named 'build-app'
# Ensure Docker is running if using a Docker executor
gitlab-ci-local build-app

# Run with specific environment variables using the new recommended syntax (v4.70.0+)
GCL_VARIABLE_MY_ENV=production gitlab-ci-local deploy

view raw JSON →