Since a few months ago this is possible using gitlab-runner:

gitlab-runner exec docker my-job-name

Note that you need both docker and gitlab-runner installed on your computer to get this working.

You also need the image key defined in your .gitlab-ci.yml file. Otherwise won't work.

Here's the line I currently use for testing locally using gitlab-runner:

gitlab-runner exec docker test --docker-volumes "/home/elboletaire/.ssh/id_rsa:/root/.ssh/id_rsa:ro"

Note: You can avoid adding a --docker-volumes with your key setting it by default in /etc/gitlab-runner/config.toml. See the official documentation for more details. Also, use gitlab-runner exec docker --help to see all docker-based runner options (like variables, volumes, networks, etc.).

Due to the confusion in the comments, I paste here the gitlab-runner --help result, so you can see that gitlab-runner can make builds locally:

   gitlab-runner --help
NAME:
   gitlab-runner - a GitLab Runner

USAGE:
   gitlab-runner [global options] command [command options] [arguments...]
   
VERSION:
   1.1.0~beta.135.g24365ee (24365ee)
   
AUTHOR(S):
   Kamil Trzciński <ayufan@ayufan.eu> 
   
COMMANDS:
   exec         execute a build locally
   [...]
   
GLOBAL OPTIONS:
   --debug          debug mode [$DEBUG]
   [...]

As you can see, the exec command is to execute a build locally.

Even though there was an issue to deprecate the current gitlab-runner exec behavior, it ended up being reconsidered and a new version with greater features will replace the current exec functionality.

Note that this process is to use your own machine to run the tests using docker containers. This is not to define custom runners. To do so, just go to your repo's CI/CD settings and read the documentation there. If you wanna ensure your runner is executed instead of one from gitlab.com, add a custom and unique tag to your runner, ensure it only runs tagged jobs and tag all the jobs you want your runner to be responsible of.

Unofficial alternative gitlab-ci-local

There's an unofficial package which looks promising, with more features than the official gitlab-runner exec: https://github.com/firecow/gitlab-ci-local

It allows you to run gitlab pipelines locally as shell executor or docker executor.

Answer from elboletaire on Stack Overflow
🌐
GitLab
docs.gitlab.com › gitlab docs › install › configure gitlab runner › commands
GitLab Runner commands | GitLab Docs
It reads all defined runners from config.toml and tries to run all of them. The command is executed and works until it receives a signal. It accepts the following parameters. ... Ability to use a configuration file introduced in GitLab Runner 17.1.
🌐
GitLab
docs.gitlab.com › gitlab docs › administer › administer gitlab runner › runner executors
Executors | GitLab Docs
If the builds use services installed on the build machine, selecting executors is possible but problematic. ↩︎ · Requires manual dependency installation. ↩︎ ↩︎ · For example, using Vagrant. ↩︎ ↩︎ · Support added in GitLab Runner 14.2. Refer to the Overriding the base VM image section for further details.
Discussions

Use GitLab CI to run tests locally? - Stack Overflow
Note: You can avoid adding a --docker-volumes with your key setting it by default in /etc/gitlab-runner/config.toml. See the official documentation for more details. Also, use gitlab-runner exec docker --help to see all docker-based runner options (like variables, volumes, networks, etc.). More on stackoverflow.com
🌐 stackoverflow.com
Testing rules with `gitlab-runner exec`
But it seems that gitlab-runner exec executes a job regardless of the rules: for example, I have an if rule which checks the value of a variable, and the job is executed even if the variable is not defined at all. For example, this job: deploy-env-cvmfs-centos7: rules: - if: ... More on forum.gitlab.com
🌐 forum.gitlab.com
2
0
October 19, 2023
testing - Any altenatives of "gitlab-runner exec docker <job-name>" to test CI/CD locally? I get "FATAL: Command exec not found." - Stack Overflow
I would like to test the .gitlab-ci.yml in local, Im following other posts like: Run tests locally gitlab, using the command: gitlab-runner exec docker . Im using gitlab-runner 17.... More on stackoverflow.com
🌐 stackoverflow.com
How to use gitlab-runner exec docker correclty - GitLab CI/CD - GitLab Forum
Here is what I did Installed gitlab-runner on my local machine. sudo gitlab-runner exec docker --docker-privileged --builds-dir /tmp/builds --docker-volumes /home/fox/Work/docker/core-application:/core-application Rspec This gives Runtime platform arch=amd64 os=linux pid=632331 revision=8fa89735 ... More on forum.gitlab.com
🌐 forum.gitlab.com
0
December 15, 2020
🌐
GitLab
gitlab.com › gitlab.org › #385235
Deprecation of the `gitlab-runner exec` command from GitLab Runner (#385235) · Issues · GitLab.org / GitLab · GitLab
For guidance on the overall deprecations, removals and breaking changes workflow, please visit Breaking changes, deprecations, and removing features ...
🌐
GitLab
gitlab.com › gitlab.org › gitlab-runner › #312
gitlab-runner exec: easily test builds locally (#312) · Issues · GitLab.org / gitlab-runner · GitLab
I just pushed a brand new feature to GitLab Runner: exec. It allows you to run the jobs defined in .gitlab-ci.yml locally!
🌐
GitLab
gitlab.com › gitlab.org › gitlab-runner › #4275
How to use exec command with the dockerized version of gitlab-runner (#4275) · Issues · GitLab.org / gitlab-runner · GitLab
Summary Trying to debug a failing gitlab ci job by using the docker gitlab-runner exec functionality. But it fails right away...
🌐
GitLab
gitlab.com › gitlab.org › gitlab-runner › repository
docs/commands · fd98f3b671c5ee4fb8fd54a41c7a242eb73a91d9 · GitLab.org / gitlab-runner · GitLab
This command installs GitLab Runner as a service. It accepts different sets of arguments depending on which system it's run on. When run on Windows or as super-user, it accepts the --user flag which allows you to drop privileges of builds run ...
Top answer
1 of 11
237

Since a few months ago this is possible using gitlab-runner:

gitlab-runner exec docker my-job-name

Note that you need both docker and gitlab-runner installed on your computer to get this working.

You also need the image key defined in your .gitlab-ci.yml file. Otherwise won't work.

Here's the line I currently use for testing locally using gitlab-runner:

gitlab-runner exec docker test --docker-volumes "/home/elboletaire/.ssh/id_rsa:/root/.ssh/id_rsa:ro"

Note: You can avoid adding a --docker-volumes with your key setting it by default in /etc/gitlab-runner/config.toml. See the official documentation for more details. Also, use gitlab-runner exec docker --help to see all docker-based runner options (like variables, volumes, networks, etc.).

Due to the confusion in the comments, I paste here the gitlab-runner --help result, so you can see that gitlab-runner can make builds locally:

   gitlab-runner --help
NAME:
   gitlab-runner - a GitLab Runner

USAGE:
   gitlab-runner [global options] command [command options] [arguments...]
   
VERSION:
   1.1.0~beta.135.g24365ee (24365ee)
   
AUTHOR(S):
   Kamil Trzciński <ayufan@ayufan.eu> 
   
COMMANDS:
   exec         execute a build locally
   [...]
   
GLOBAL OPTIONS:
   --debug          debug mode [$DEBUG]
   [...]

As you can see, the exec command is to execute a build locally.

Even though there was an issue to deprecate the current gitlab-runner exec behavior, it ended up being reconsidered and a new version with greater features will replace the current exec functionality.

Note that this process is to use your own machine to run the tests using docker containers. This is not to define custom runners. To do so, just go to your repo's CI/CD settings and read the documentation there. If you wanna ensure your runner is executed instead of one from gitlab.com, add a custom and unique tag to your runner, ensure it only runs tagged jobs and tag all the jobs you want your runner to be responsible of.

Unofficial alternative gitlab-ci-local

There's an unofficial package which looks promising, with more features than the official gitlab-runner exec: https://github.com/firecow/gitlab-ci-local

It allows you to run gitlab pipelines locally as shell executor or docker executor.

2 of 11
189

Deprecated since 2024-05 (see edit)

Only for gitlab-runner < 17.0.

  • See gitlab issue.
  • See gitlab docu

I use this docker-based approach:

Edit: 2024-05

docker run --entrypoint bash --rm -w "PWD:$PWD" -v /var/run/docker.sock:/var/run/docker.sock gitlab/gitlab-runner:v15.11.1 -c 'git config --global --add safe.directory "*";gitlab-runner exec docker test'

Thanks to user Ivo Smits who reported a successful test with gitlab-runner:v15.11.1

Edit: 2022-10

For all git versions > 2.35.2. You must add safe.directory within the container to avoid fatal: detected dubious ownership in repository at.... This also true for patched git versions < 2.35.2. The old command will not work anymore.

Details

0. Create a git repo to test this answer

mkdir my-git-project
cd my-git-project
git init
git commit --allow-empty -m"Initialize repo to showcase gitlab-runner locally."

1. Go to your git directory

cd my-git-project

2. Create a .gitlab-ci.yml

Example .gitlab-ci.yml

image: alpine

test:
  script:
    - echo "Hello Gitlab-Runner"

3. Create a docker container with your project dir mounted

docker run -d \
  --name gitlab-runner \
  --restart always \
  -v "PWD" \
  -v /var/run/docker.sock:/var/run/docker.sock \
  gitlab/gitlab-runner:latest

(-d) run container in background and print container ID

(--restart always) or not?

(-v "PWD") Mount current directory into the current directory of the container - Note: On Windows you could bind your dir to a fixed location, e.g. -v "${PWD}:/opt/myapp". Also $PWD will only work at powershell not at cmd

(-v /var/run/docker.sock:/var/run/docker.sock) This gives the container access to the docker socket of the host so it can start "sibling containers" (e.g. Alpine).

(gitlab/gitlab-runner:latest) Just the latest available image from dockerhub.

4. Execute with

Avoid fatal: detected dubious ownership in repository at... More info

docker exec -it -w $PWD gitlab-runner git config --global --add safe.directory "*"

Actual execution

docker exec -it -w $PWD gitlab-runner gitlab-runner exec docker test
#                ^          ^           ^            ^     ^      ^
#                |          |           |            |     |      |
#               (a)        (b)         (c)          (d)   (e)    (f)

(a) Working dir within the container. Note: On Windows you could use a fixed location, e.g. /opt/myapp.

(b) Name of the docker container

(c) Execute the command "gitlab-runner" within the docker container

(d)(e)(f) run gitlab-runner with "docker executer" and run a job named "test"

5. Prints

...
Executing "step_script" stage of the job script
$ echo "Hello Gitlab-Runner"
Hello Gitlab-Runner
Job succeeded
...

Note: The runner will only work on the commited state of your code base. Uncommited changes will be ignored. Exception: The .gitlab-ci.yml itself does not have be commited to be taken into account.

Note: There are some limitations running locally. Have a look at limitations of gitlab runner locally.

🌐
GitLab
forum.gitlab.com › gitlab ci/cd
Testing rules with `gitlab-runner exec` - GitLab CI/CD - GitLab Forum
October 19, 2023 - But it seems that gitlab-runner exec executes a job regardless of the rules: for example, I have an if rule which checks the value of a variable, and the job is executed even if the variable is not defined at all.
Find elsewhere
🌐
Stack Overflow
stackoverflow.com › questions › 78661760 › any-altenatives-of-gitlab-runner-exec-docker-job-name-to-test-ci-cd-locally
testing - Any altenatives of "gitlab-runner exec docker <job-name>" to test CI/CD locally? I get "FATAL: Command exec not found." - Stack Overflow
For example, for the job of linting python in gitlab CI/CD: lint-before-merge: stage: linting image: python:3.12 rules: - if: ($CI_PIPELINE_SOURCE == "merge_request_event" && ($CI_MERGE_REQUEST_TARGET_BRANCH_NAME == "develop"|| $CI_MERGE_REQUEST_TARGET_BRANCH_NAME == "main")) script: - pip install flake8 - flake8 . ... sudo docker run -it --rm --name my-running-script -w "/app" -v "$PWD":"/app" python:3.12 /bin/bash -c "pip install flake8 ; flake8 --exclude venv ; echo "executed""
🌐
GitLab
docs.gitlab.com › gitlab docs › administer › administer gitlab runner › runner executors › shell
The Shell executor | GitLab Docs
The shell executor starts the script for each job in a new process. On UNIX systems, it sets the main process as a process group. ... A job times out. A job is canceled. On UNIX system gitlab-runner sends SIGTERM to the process and its child processes, and after 10 minutes sends SIGKILL.
🌐
GitLab
docs.gitlab.com › gitlab docs › administer › administer gitlab runner
GitLab Runner | GitLab Docs
This diagram shows how runners are registered and how jobs are requested and handled. It also shows which actions use registration and authentication tokens, and job tokens. sequenceDiagram participant GitLab participant GitLabRunner participant Executor opt registration GitLabRunner ->>+ GitLab: POST /api/v4/runners with registration_token GitLab -->>- GitLabRunner: Registered with runner_token end loop job requesting and handling GitLabRunner ->>+ GitLab: POST /api/v4/jobs/request with runner_token GitLab -->>+ GitLabRunner: job payload with job_token GitLabRunner ->>+ Executor: Job payload Executor ->>+ GitLab: clone sources with job_token Executor ->>+ GitLab: download artifacts with job_token Executor -->>- GitLabRunner: return job output and status GitLabRunner -->>- GitLab: updating job output and status with job_token end
🌐
DevOpsSchool.com
devopsschool.com › blog › gitlab-tutorials-gitlab-runner-commands-line-reference-and-example
GitLab Tutorials: gitlab-runner commands line reference and example
NAME: gitlab-runner - a GitLab Runner USAGE: gitlab-runner [global options] command [command options] [arguments...] VERSION: 15.3.0 (bbcb5aba) AUTHOR: GitLab Inc. <support@gitlab.com> COMMANDS: exec execute a build locally list List all configured ...
🌐
Lullabot
lullabot.com › articles › debugging-jobs-gitlab-ci
Debugging Jobs in GitLab CI | Lullabot
December 27, 2025 - Run the job with the command gitlab-runner exec docker [job id goes here].
🌐
BrowserStack
browserstack.com › home › guide › how to run test on gitlab ci locally
How to run test on GitLab CI Locally | BrowserStack
May 30, 2023 - Explore the shell executor. ... Gitlab-runner exec is the command that helps test locally. The exec command should be executed directly from the root directory because .gitlab-ci.yml will be kept in the root directory.
🌐
GitLab
gitlab.com › gitlab.org › gitlab-runner › repository
commands/exec.go · v12.5.0 · GitLab.org / gitlab-runner · GitLab
July 8, 2019 - GitLab Runner is the open source project that is used to run your CI/CD jobs and send the results back to GitLab
🌐
GitLab
forum.gitlab.com › gitlab ci/cd
How to use gitlab-runner exec docker correclty - GitLab CI/CD - GitLab Forum
December 15, 2020 - Here is what I did Installed gitlab-runner on my local machine. sudo gitlab-runner exec docker --docker-privileged --builds-dir /tmp/builds --docker-volumes /home/fox/Work/docker/core-application:/core-application Rspec This gives Runtime platform ...
🌐
GitHub
gist.github.com › DrPsychick › b92c2653c1132c3be6da2c3bb42905d4
Run gitlab-ci jobs locally · GitHub
docker run --rm -d \ --name gitlab-runner \ -v $PWD:$PWD \ -v /var/run/docker.sock:/var/run/docker.sock \ gitlab/gitlab-runner:latest · If you use template jobs (.test) then specify those as job. docker exec -it -w $PWD gitlab-runner gitlab-runner exec docker <job>
🌐
GitLab
gitlab.com › gitlab.org › repository
data/deprecations/15-7-deprecate-gitlab-runner-exec-cmd.yml · f123b226a82907b207643dd62519339b582f7772 · GitLab.org / GitLab · GitLab
GitLab is an open source end-to-end software development platform with built-in version control, issue tracking, code review, CI/CD, and more. Self-host GitLab on your own servers, in a...