GitLab Documentation

Run GitLab Runner in a container

This is how you can run GitLab Runner inside a Docker container.

Docker image installation and configuration

  1. Install Docker first:

    curl -sSL | sh
  2. You need to mount a config volume into the gitlab-runner container to be used for configs and other resources:

    docker run -d --name gitlab-runner --restart always \
      -v /srv/gitlab-runner/config:/etc/gitlab-runner \
      -v /var/run/docker.sock:/var/run/docker.sock \

    On OSX, substitute the path "/Users/Shared" for "/srv".

    Or, you can use a config container to mount your custom data volume:

    docker run -d --name gitlab-runner-config \
        -v /etc/gitlab-runner \
        busybox:latest \
    docker run -d --name gitlab-runner --restart always \
        --volumes-from gitlab-runner-config \

    If you plan on using Docker as the method of spawning Runners, you will need to mount your docker socket like this:

    docker run -d --name gitlab-runner --restart always \
      -v /var/run/docker.sock:/var/run/docker.sock \
      -v /srv/gitlab-runner/config:/etc/gitlab-runner \
  3. Register the Runner

Make sure that you read the FAQ section which describes some of the most common problems with GitLab Runner.


Pull the latest version:

docker pull gitlab/gitlab-runner:latest

Stop and remove the existing container:

docker stop gitlab-runner && docker rm gitlab-runner

Start the container as you did originally:

docker run -d --name gitlab-runner --restart always \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v /srv/gitlab-runner/config:/etc/gitlab-runner \

Note: you need to use the same method for mounting you data volume as you did originally (-v /srv/gitlab-runner/config:/etc/gitlab-runner or --volumes-from gitlab-runner).

Installing trusted SSL server certificates

If your GitLab CI server is using self-signed SSL certificates then you should make sure the GitLab CI server certificate is trusted by the gitlab-runner container for them to be able to talk to each other.

The gitlab/gitlab-runner image is configured to look for the trusted SSL certificates at /etc/gitlab-runner/certs/ca.crt, this can however be changed using the -e "CA_CERTIFICATES_PATH=/DIR/CERT" configuration option.

Copy the ca.crt file into the certs directory on the data volume (or container). The ca.crt file should contain the root certificates of all the servers you want gitlab-runner to trust. The gitlab-runner container will import the ca.crt file on startup so if your container is already running you may need to restart it for the changes to take effect.

Alpine Linux

You can also use alternative Alpine Linux based image with much smaller footprint:

gitlab/gitlab-runner    latest              3e8077e209f5        13 hours ago        304.3 MB
gitlab/gitlab-runner    alpine              7c431ac8f30f        13 hours ago        25.98 MB

Alpine Linux image is designed to use only Docker as the method of spawning runners.

The original gitlab/gitlab-runner:latest is based on Ubuntu 14.04 LTS.


Some distributions (CentOS, RedHat, Fedora) use SELinux by default to enhance the security of the underlying system.

The special care must be taken when dealing with such configuration.

  1. If you want to use Docker executor to run builds in containers you need to access the /var/run/docker.sock. However, if you have a SELinux in enforcing mode, you will see the Permission denied when accessing the /var/run/docker.sock. Install the selinux-dockersock and to resolve the issue:

  2. Make sure that persistent directory is created on host: mkdir -p /srv/gitlab-runner/config.

  3. Run docker with :Z on volumes:

docker run -d --name gitlab-runner --restart always \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v /srv/gitlab-runner/config:/etc/gitlab-runner:Z \

More information about the cause and resolution can be found here:

Leave a comment below if you have any feedback on the documentation. For support and other inquires, see getting help.