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:

1. The runner starts a Docker container using the defined entrypoint. The default from Dockerfile
    that may be overridden in the .gitlab-ci.yml file.
2. The runner attaches itself to a running container.
3. The runner prepares a script (the combination of before_script, script, and after_script).
4. 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

• 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’s config.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.

1. Per-job: To configure one job to access a private registry, add DOCKER_AUTH_CONFIG as a CI/CD variable.
2. 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.