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
Dockerfile
that may be overridden in the.gitlab-ci.yml
file. - 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
stdin
and 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
entrypoint
can be set to an empty value. - For Docker 17.03 and earlier, the
entrypoint
can 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
ENTRYPOINT
to 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_CONFIG
CI/CD variable. - A
DOCKER_AUTH_CONFIG
environment variable set in the runner’sconfig.toml
file. - A
config.json
file in$HOME/.docker
directory of the user running the process. If the--user
flag 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_CONFIG
as a CI/CD variable. - Per-runner: To configure a runner so all its jobs can access a private registry, add
DOCKER_AUTH_CONFIG
as an environment variable in the runner’s configuration.