mrVanboy/giltab-runner-local-docker.md

## giltab-runner-local-docker.md

      
    Raw
  

              giltab-runner-local-docker.md
            
          
    Debugging Gitlab CI jobs locally

You can find a bunch of articles about debugging Gitlab CI jobs locally. My top results from google:

[SmallTips] Running GitLab CI Runner Locally | AkitaOnRails.com
How to: Debug GitLab CI Builds Locally | Substrakt
Debugging Gitlab CI pipelines locally – Campfire Code – Medium

But in all that articles the described way is to install Docker and gitlab-runner executable,
run gitlab-runner exec docker JOB_NAME_FROM_GITLAB_CI_YML after that in your repo.
I don't like this approach because I want a simpler way to run appropriate gitlab-runner executable and don't
want to have this executable in my system. Why do it if we can run it inside docker? And gitlab also provides
appropriate images on dockerhub: gitlab/gitlab-runner.
Requirements:


Docker

Quickstart

Run inside the root directory of your repo:
docker run --rm -ti \
            -v `pwd`:/`pwd`:ro \
            -v /var/run/docker.sock:/var/run/docker.sock \
            -w `pwd` \
            gitlab/gitlab-runner:alpine \
            exec docker JOB_NAME_FROM_GITLAB_CI_YML \
            --docker-volumes /var/run/docker.sock:/var/run/docker.sock
What it actually does

Image gitlab/gitlab-runner:alpine has custom entrypoint that actually is wrapper around gitlab-runner command.
Look to the official repo of gitlab-runner
for more information.
Also we need to allow runner inside container to connect to our local docker socket. We just map it as volume inside
-v /var/run/docker.sock:/var/run/docker.sock.
We need to map our current directory again as volume with parameter -v pwd:/pwd:ro in read-only (just in case if
something will go wrong). Directory inside the container should be the same as at our local machine because of gitlab-runner
will create another container, try to map another volume inside the newly created container, but docker is run on our host
machine and it can map only our local directories.
To run a job from .gitlab-ci.yml we need to pass the parameters exec docker JOB_NAME_FROM_GITLAB_CI_YML.

exec is for executing job locally
docker is for choosing Docker executor

Optionally if you want to run jobs that utilize docker you need an additional step that is not described in documentation.
Otherwise jobs can fail with error: docker: Cannot connect to the Docker daemon at unix:///var/run/docker.sock. Is the docker daemon running?.
In current version gitlab-runner exec omit reading configuration from config.toml (here is mention about it)
and in default configuration it will not pass /var/run/docker.sock inside container where job is executed. Only one way
to do it is pass another argument --docker-volumes /var/run/docker.sock:/var/run/docker.sock to gotlab-runner executable.