You have to execute the command from the root folder of your git repository/project:

 $ ls -a
 ./
 ../
 .git/
 .gitignore
 .gitlab-ci.yml
 Makefile

 $ gitlab-runner exec docker <job_name>

You are using docker commands which you shouldn't as gitlab-runner already uses those under the hood. See $ gitlab-runner exec docker --help for more info on the command.

Answer from 13013SwagR on Stack Overflow
🌐
GitLab
docs.gitlab.com › gitlab docs › administer › administer gitlab runner › runner executors › docker
Docker executor | GitLab Docs
The Docker executor uses Docker Engine to run each job in a separate and isolated container. To connect to Docker Engine, the executor uses: The image and services you define in .gitlab-ci.yml. The configurations you define in config.toml. You can’t register a runner and its Docker executor ...
Top answer
1 of 2
2

You have to execute the command from the root folder of your git repository/project:

 $ ls -a
 ./
 ../
 .git/
 .gitignore
 .gitlab-ci.yml
 Makefile

 $ gitlab-runner exec docker <job_name>

You are using docker commands which you shouldn't as gitlab-runner already uses those under the hood. See $ gitlab-runner exec docker --help for more info on the command.

2 of 2
0

I also came across a similar issue when using VS Code with remote containers and Docker Desktop (WSL2).

I debugged the problem by adding in a --pre-get-sources-script=ls -l "repo_directory", i.e. in the OP's case:

# docker run --name=runner --privileged -t --rm \
 -v /var/run/docker.sock:/var/run/docker.sock  \
 -v /tmp/.gitlab-runner/:/etc/gitlab-runner \
 -v {PWD} \
 --workdir $PWD \
 --pre-get-sources-script=ls -l /home/fox/Work/docker/core-application/../.git/modules/core-application \
 gitlab/gitlab-runner exec docker \
  --builds-dir /tmp/builds/ Rspec

In my case, the directory listing (ls -l ...) came up empty! I'm assuming that it mounts the directory as a volume within the container as the same name (/fubar:/fubar), which in my case isn't going to work as it is Docker Desktop with vscode remote containers.

My fix was was to add my named volume as a parameter to a secondary directory, and then setting the --clone-url to point to that directory.

Something like:

# pwd
/workspace/fubar
# gitlab-runner --debug exec docker \
  --docker-volumes vscode-workspace:/workspace2 \
  --clone-url=file:///workspace2/fubar \
  validate;
[output truncated]
...
Starting container 3d49d8e8b977177f34beeae3ae5f09eba288332e109ad79f133e0f160377908b ...  job=1 project=0
Fetching changes...
Initialized empty Git repository in /builds/project-0/.git/
Created fresh repository.
Checking out d1a39a4d as detached HEAD (ref is feature/FU-123)...

Skipping Git submodules setup
Executing build stage                               build_stage=restore_cache job=1 project=0
Skipping stage (nothing to do)                      build_stage=restore_cache job=1 project=0
Executing build stage                               build_stage=download_artifacts job=1 project=0
Skipping stage (nothing to do)                      build_stage=download_artifacts job=1 project=0
Executing build stage                               build_stage=step_script job=1 project=0
Executing "step_script" stage of the job script
...

I had originally tried changing the --pre-get-sources-script to be cp -R /workspace2/fubar /workspace/ but that complained that the target directory was read-only. Using the --clone-url=file:///workspace2/fubar worked, so I've left it that way.

Discussions

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
Use GitLab CI to run tests locally? - Stack Overflow
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 ... More on stackoverflow.com
🌐 stackoverflow.com
How to use the docker gitlab-runner to exec stages locally - Stack Overflow
I have setup a gitlab runner in docker on my local machine. It all is working fine. When the pipeline starts, the runner seems to handle the workload But, I would like to do this locally. For examp... More on stackoverflow.com
🌐 stackoverflow.com
Trouble using gitlab-runner exec docker - How to Use GitLab - GitLab Forum
I’m trying to create a Docker image for my build environment, and run a build locally by using gitlab-runner exec. Could someone please clarify for a n00b what concept I’ve gotten wrong? My Docker image, named hughw/factordev:latest, is base Ubuntu 16.04, plus some libraries my build requires. More on forum.gitlab.com
🌐 forum.gitlab.com
0
October 30, 2017
🌐
Medium
medium.com › @BuildWithLal › dockerized-gitlab-ci-register-docker-executor-as-a-gitlab-runner-71799352c9ac
Dockerized GitLab CI: Register Docker Executor as a GitLab Runner | by Lal Zada | Medium
October 10, 2024 - When we want to execute a job using docker, GitLab Runner can create a container on our host machine using this docker.sock file, run the job and then terminate once the job is done.
🌐
GitHub
gist.github.com › DrPsychick › b92c2653c1132c3be6da2c3bb42905d4
Run gitlab-ci jobs locally · GitHub
mount the certs: exec docker --docker-volumes "/certs/client" docker run --rm --name gitlab-runner -w $PWD \ -v $PWD:$PWD -v /var/run/docker.sock:/var/run/docker.sock \ gitlab/gitlab-runner:latest exec docker <job>
🌐
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 ...
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.

Find elsewhere
🌐
Datawookie
datawookie.dev › blog › 2021 › 03 › install-gitlab-runner-with-docker
Install GitLab Runner with Docker – datawookie
March 21, 2021 - The GitLab Runner client can be used to manage the active runners. To get a list of available commands use the --help argument. docker exec -it gitlab-runner gitlab-runner --help
🌐
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
docs.gitlab.com › gitlab docs › install › configure gitlab runner › commands
GitLab Runner commands | GitLab Docs
gitlab-runner run-single -u http://gitlab.example.com -t my-runner-token --executor docker --docker-image ruby:3.3
🌐
LinkedIn
linkedin.com › pulse › how-execute-gitlab-ci-docker-your-local-machine-shubham-takode
How to execute GitLab CI with Docker on your local machine.
February 25, 2022 - #Go to your project directory and run (make sure there is gitlab-ci.yml) $sudo gitlab-runner exec docker build #where build is the stage from your .gitlab-ci.yml you want to execute
🌐
GitLab
gitlab.com › gitlab.org › gitlab-runner › #3295
Use local docker images with gitlab-runner exec docker (#3295) · Issues · GitLab.org / gitlab-runner · GitLab
I would like to debug my build locally but I would like to avoid having to build the docker image once again (I have it locally to develop, but I would have to build it again for gitlab-runner). In order to do so, I'm mounting a volume of the Docker socket file and passing it to the docker executor, but docker can't see my images (in my `test` stage, I have a `docker images` to see what is available): ```sh $ docker run --rm -it -v "$PWD":"$PWD" --workdir "$PWD" -v /var/run/docker.sock:/var/run/docker.sock gitlab/gitlab-runner:alpine-v10.7.1 exec docker --docker-privileged --docker-pull-policy if-not-present --docker-volumes /var/run/docker.sock:/var/run/docker.sock test WARNING: You most probably have uncommitted changes.
🌐
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].
🌐
GitLab
docs.gitlab.com › gitlab docs › use gitlab › use ci/cd to build your application › jobs › docker › use docker to build docker images
Use Docker to build Docker images | GitLab Docs
May 8, 2023 - To mount /var/run/docker.sock while registering your runner, include the following options: sudo gitlab-runner register \ --non-interactive \ --url "https://gitlab.com/" \ --registration-token REGISTRATION_TOKEN \ --executor "docker" \ --description "docker-runner" \ --tag-list "socket-binding-docker-runner" \ --docker-image "docker:24.0.5-cli" \ --docker-volumes "/var/run/docker.sock:/var/run/docker.sock"
🌐
GitLab
gitlab.com › gitlab.org › gitlab-runner › merge requests › !1026
Add documentation how to exec docker locally in privileged mode (!1026) · Merge requests · GitLab.org / gitlab-runner · GitLab
December 15, 2020 - This is just an update for gitlab-runner documentation on adding --docker-privileged flag to gitlab-runner exec docker <jobname> command when services are used, which would result in following error if not provided:
🌐
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. ↩︎ ↩︎ ... Bash shell is not supported on Windows. ↩︎ · Default shell for jobs with the docker-windows and kubernetes executors.
🌐
GitLab
forum.gitlab.com › how to use gitlab
Trouble using gitlab-runner exec docker - How to Use GitLab - GitLab Forum
October 30, 2017 - I’m trying to create a Docker image for my build environment, and run a build locally by using gitlab-runner exec. Could someone please clarify for a n00b what concept I’ve gotten wrong? My Docker image, named hughw/fac…
🌐
GitHub
gist.github.com › NikiforovAll › 7294ce1a72bdcfbf4159896853589b9f
GitLab Runner + Docker · GitHub
docker run -d \ --name gitlab-runner \ --restart always \ -v $PWD:$PWD \ -v /var/run/docker.sock:/var/run/docker.sock \ gitlab/gitlab-runner:latest · Run job: docker exec -it -w $PWD gitlab-runner gitlab-runner exec docker <jobName>
🌐
TestDriven.io
testdriven.io › blog › gitlab-ci-docker
Deploying Self-Hosted GitLab CI Runners with Docker | TestDriven.io
October 29, 2021 - Before we update the concurrency options, add a new runner: $ docker-compose exec gitlab-runner-container \ gitlab-runner register \ --non-interactive \ --url <YOUR-GITLAB-URL> \ --registration-token <YOUR-GITLAB-REGISTRATION-TOKEN> \ --executor docker \ --description "Sample Runner 2" \ --docker-image "docker:stable" \ --docker-volumes /var/run/docker.sock:/var/run/docker.sock