{"id":14597,"library":"gitlab-ci-local","title":"Run GitLab CI Pipelines Locally","description":"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.","status":"active","version":"4.71.0","language":"javascript","source_language":"en","source_url":"https://github.com/firecow/gitlab-ci-local","tags":["javascript","git","gitlab","pipeline","local","ci","cd","push","untracked"],"install":[{"cmd":"npm install gitlab-ci-local","lang":"bash","label":"npm"},{"cmd":"yarn add gitlab-ci-local","lang":"bash","label":"yarn"},{"cmd":"pnpm add gitlab-ci-local","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[],"quickstart":{"code":"npm install -g gitlab-ci-local\n# Navigate to your GitLab project directory\ncd my-gitlab-project\n# List all available jobs in your .gitlab-ci.yml\ngitlab-ci-local --list\n\n# Run a specific job named 'build-app'\n# Ensure Docker is running if using a Docker executor\ngitlab-ci-local build-app\n\n# Run with specific environment variables using the new recommended syntax (v4.70.0+)\nGCL_VARIABLE_MY_ENV=production gitlab-ci-local deploy","lang":"bash","description":"Demonstrates global installation, listing available CI jobs, and running a specific job with environment variables."},"warnings":[{"fix":"Migrate environment variable definitions from `yargs .env(\"GCL\")` styles to the new `GCL_VARIABLE_MY_VAR=value` format.","message":"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.","severity":"breaking","affected_versions":">=4.70.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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`.","message":"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.","severity":"gotcha","affected_versions":"<4.71.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=4.68.1"},{"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.","message":"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.","severity":"gotcha","affected_versions":"<4.70.1"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Install globally via `npm install -g gitlab-ci-local` or execute using `npx gitlab-ci-local <command>`.","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.","error":"'gitlab-ci-local' is not recognized as an internal or external command, operable program or batch file."},{"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).","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.","error":"Error: Cannot connect to the Docker daemon at unix:///var/run/docker.sock. Is the docker daemon running?"},{"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.","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.","error":"Job 'my-job' not found or cannot be selected."},{"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.","cause":"Automatic `.env` file loading is explicitly disabled in compiled binaries or when certain package managers like Bun are used, to prevent unexpected behavior.","error":"Error: .env autoload in compiled binaries disabled. Please specify with --dotenv-file option."}],"ecosystem":"npm"}