Override the entrypoint of an image
Introduced in GitLab and GitLab Runner 9.4. Read more about the extended configuration options.
Before explaining the available entrypoint override methods, let’s describe how the runner starts. It uses a Docker image for the containers used in the CI/CD jobs:
- The runner starts a Docker container using the defined entrypoint. The default from
Dockerfilethat may be overridden in the.gitlab-ci.ymlfile. - The runner attaches itself to a running container.
- The runner prepares a script (the combination of
before_script,script, andafter_script). - The runner sends the script to the container’s shell
stdinand receives the output.
To override the entrypoint of a Docker image, define an empty entrypoint in the .gitlab-ci.yml file, so the runner does not start a useless shell layer. However, that does not work for all Docker versions.
- For Docker 17.06 and later, the
entrypointcan be set to an empty value. - For Docker 17.03 and earlier, the
entrypointcan be set to/bin/sh -c,/bin/bash -c, or an equivalent shell available in the image.
The syntax of image:entrypoint is similar to Dockerfile’s ENTRYPOINT.
Let’s assume you have a super/sql:experimental image with a SQL database in it. You want to use it as a base image for your job because you want to execute some tests with this database binary. Let’s also assume that this image is configured with /usr/bin/super-sql run as an entrypoint. When the container starts without additional options, it runs the database’s process. The runner expects that the image has no entrypoint or that the entrypoint is prepared to start a shell command.
With the extended Docker configuration options, instead of:
- Creating your own image based on
super/sql:experimental. - Setting the
ENTRYPOINTto a shell. - Using the new image in your CI job.
You can now define an entrypoint in the .gitlab-ci.yml file.
For Docker 17.06 and later:
image:
name: super/sql:experimental
entrypoint: [""]
For Docker 17.03 and earlier:
image:
name: super/sql:experimental
entrypoint: ["/bin/sh", "-c"]
Define image and services in config.toml
Look for the [runners.docker] section:
[runners.docker]
image = "ruby:latest"
services = ["mysql:latest", "postgres:latest"]
The image and services defined this way are added to all jobs run by that runner.
Access an image from a private Container Registry
To access private container registries, the GitLab Runner process can use:
- Statically defined credentials. That is, a username and password for a specific registry.
- Credentials Store. For more information, see the relevant Docker documentation.
- Credential Helpers. For more information, see the relevant Docker documentation.
To define which option should be used, the runner process reads the configuration in this order:
- A
DOCKER_AUTH_CONFIGCI/CD variable. - A
DOCKER_AUTH_CONFIGenvironment variable set in the runner’sconfig.tomlfile. - A
config.jsonfile in$HOME/.dockerdirectory of the user running the process. If the--userflag is provided to run the child processes as unprivileged user, the home directory of the main runner process user is used.
Requirements and limitations
- Available for Kubernetes executor in GitLab Runner 13.1 and later.
- Credentials Store and Credential Helpers require binaries to be added to the GitLab Runner
$PATH, and require access to do so. Therefore, these features are not available on shared runners, or any other runner where the user does not have access to the environment where the runner is installed.
Use statically-defined credentials
There are two approaches that you can take to access a private registry. Both require setting the CI/CD variable DOCKER_AUTH_CONFIG with appropriate authentication information.
- Per-job: To configure one job to access a private registry, add
DOCKER_AUTH_CONFIGas a CI/CD variable. - Per-runner: To configure a runner so all its jobs can access a private registry, add
DOCKER_AUTH_CONFIGas an environment variable in the runner’s configuration.