- Getting started
- List of runners using this image
If you find this image useful here's how you can help:
- Send a pull request with your awesome features and bug fixes
- Help users resolve their issues.
- Support the development of this image with a donation
Before reporting your issue please try updating Docker to the latest version and check if it resolves the issue. Refer to the Docker installation guide for instructions.
SELinux users should try disabling SELinux using the command
setenforce 0 to see if it resolves the issue.
If the above recommendations do not help then report your issue along with the following information:
- Output of the
docker runcommand or
docker-compose.ymlused to start the image. Mask out the sensitive bits.
- Please state if you are using Boot2Docker, VirtualBox, etc.
Automated builds of the image are available on Dockerhub and is the recommended method of installation.
Note: Builds are also available on Quay.io
docker pull digitallumberjack/docker-gitlab-ci-multi-runner:v10.7.0
Alternatively you can build the image yourself.
docker build -t sameersbn/gitlab-ci-multi-runner github.com/sameersbn/docker-gitlab-ci-multi-runner
Before a runner can process your CI jobs, it needs to be authorized to access the the GitLab CI server. The
RUNNER_EXECUTOR environment variables are used to register the runner on GitLab CI.
You can use any ENV variable supported by the gitlab ci runner.
docker run --name gitlab-ci-multi-runner -d --restart=always \ --volume /srv/docker/gitlab-runner:/home/gitlab_ci_multi_runner/data \ --env='CI_SERVER_URL=http://git.example.com/ci' --env='RUNNER_TOKEN=xxxxxxxxx' \ --env='RUNNER_DESCRIPTION=myrunner' --env='RUNNER_EXECUTOR=shell' \ digitallumberjack/docker-gitlab-ci-multi-runner:v10.7.0
Update the values of
RUNNER_DESCRIPTION in the above command. If these enviroment variables are not specified, you will be prompted to enter these details interactively on first run.
You can customise the runner with the following env variables:
- CA_CERTIFICATES_PATH: the path to your certificate
- RUNNER_CONCURRENT: the number of concurrent job the runner can start
- CI_SERVER_URL: your server URL (suffixed by /ci)
- RUNNER_TOKEN: the runner token corresponding to your project
- RUNNER_EXECUTOR: the executor to start
- RUNNER_DESCRIPTION: the description of the runner, displayed in gitlab ui
- RUNNER_DOCKER_IMAGE: the default image to run when starting a build
- RUNNER_DOCKER_MODE: the docker mode to use, socket or dind
- RUNNER_DOCKER_PRIVATE_REGISTRY_URL: url of private registry the runner should access
- RUNNER_DOCKER_PRIVATE_REGISTRY_TOKEN: token of private registry the runner should access
- RUNNER_DOCKER_ADDITIONAL_VOLUME: additionals volumes to share between host and jobs (multiple volumes must be separated by a space)
- RUNNER_OUTPUT_LIMIT: output limit in KB that a build can produce
- RUNNER_AUTOUNREGISTER: auto unregister the runner when the container stops
Using docker executor
You can use the docker executor by using
RUNNER_EXECUTOR=docker. You must provide a docker image to use in
RUNNER_DOCKER_IMAGE (e.g. docker:latest)
RUNNER_DOCKER_MODE is set to
socket, the docker socket is shared between the runner and the build container. If it is not, you must use docker in docker service in your .gitlabci.yml definitions.
Start the docker runner in socket mode :
docker run --name gitlab-ci-multi-runner -d --restart=always \ --volume /var/run/docker.sock:/var/run/docker.sock --volume /srv/docker/gitlab-runner:/home/gitlab_ci_multi_runner/data \ --env='CI_SERVER_URL=http://git.example.com/ci' --env='RUNNER_TOKEN=xxxxxxxxx' \ --env='RUNNER_DESCRIPTION=myrunner' --env='RUNNER_EXECUTOR=docker' \ --env='RUNNER_DOCKER_IMAGE=docker:latest' --env='RUNNER_DOCKER_MODE=socket' digitallumberjack/docker-gitlab-ci-multi-runner:v10.7.0
Start the docker runner in dind mode :
docker run --name gitlab-ci-multi-runner -d --restart=always \ --volume /var/run/docker.sock:/var/run/docker.sock --volume /srv/docker/gitlab-runner:/home/gitlab_ci_multi_runner/data \ --env='CI_SERVER_URL=http://git.example.com/ci' --env='RUNNER_TOKEN=xxxxxxxxx' \ --env='RUNNER_DESCRIPTION=myrunner' --env='RUNNER_EXECUTOR=docker' \ --env='RUNNER_DOCKER_IMAGE=docker:latest' --env='RUNNER_DOCKER_MODE=dind' digitallumberjack/docker-gitlab-ci-multi-runner:v10.7.0
If you want to share volumes between your containers and the runner in socket mode, use the
RUNNER_DOCKER_ADDITIONAL_VOLUME variable to share
You can increase the log maximum size by setting the RUNNER_OUTPUT_LIMIT variable (in kb)
See https://docs.gitlab.com/ce/ci/docker/using_docker_build.html for more info.
You an setup your runner to start multiple job in parallel by setting the environment variable
RUNNER_CONCURRENT to the number of jobs you want to run concurrently.
You can customize the launch command by specifying arguments to
gitlab-ci-multi-runner on the
docker run command. For example the following command prints the help menu of
docker run --name gitlab-ci-multi-runner -it --rm \ --volume /srv/docker/gitlab-runner:/home/gitlab_ci_multi_runner/data \ digitallumberjack/docker-gitlab-ci-multi-runner:v10.7.0 --help
For the image to preserve its state across container shutdown and startup you should mount a volume at
The Quickstart command already mounts a volume for persistence.
SELinux users should update the security context of the host mountpoint so that it plays nicely with Docker:
mkdir -p /srv/docker/gitlab-runner chcon -Rt svirt_sandbox_file_t /srv/docker/gitlab-runner
At first run the image automatically generates SSH deploy keys which are installed at
/home/gitlab_ci_multi_runner/data/.ssh of the persistent data store. You can replace these keys with your own if you wish to do so.
You can use these keys to allow the runner to gain access to your private git repositories over the SSH protocol.
- The deploy keys are generated without a passphrase.
- If your CI jobs clone repositories over SSH, you will need to build the ssh known hosts file which can be done in the build steps using, for example,
ssh-keyscan github.com | sort -u - ~/.ssh/known_hosts -o ~/.ssh/known_hosts.
Trusting SSL Server Certificates
If your GitLab server is using self-signed SSL certificates then you should make sure the GitLab server's SSL certificate is trusted on the runner for the git clone operations to work.
The runner is configured to look for trusted SSL certificates at
/home/gitlab_ci_multi_runner/data/certs/ca.crt. This path can be changed using the
CA_CERTIFICATES_PATH enviroment variable.
Create a file named
ca.crt in a
certs folder at the root of your persistent data volume. The
ca.crt file should contain the root certificates of all the servers you want to trust.
Similarly you should also trust the SSL certificate of the GitLab CI server by appending the contents of the
gitlab-ci.crt file to
To upgrade to newer releases:
Download the updated Docker image:
docker pull digitallumberjack/docker-gitlab-ci-multi-runner:v10.7.0
Stop the currently running image:
docker stop gitlab-ci-multi-runner
Remove the stopped container
docker rm -v gitlab-ci-multi-runner
Start the updated image
docker run -name gitlab-ci-multi-runner -d \ [OPTIONS] \ digitallumberjack/docker-gitlab-ci-multi-runner:v10.7.0
For debugging and maintenance purposes you may want access the containers shell. If you are using Docker version
1.3.0 or higher you can access a running containers shell by starting
docker exec -it gitlab-ci-multi-runner bash
List of runners using this image
- docker-gitlab-ci-multi-runner-ruby to run ruby builds