Override the entrypoint of an image

Introduced in GitLab and GitLab Runner 9.4. Read more about theextended 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 fromDockerfilethat may be overridden in the.gitlab-ci.ymlfile.
2. The runner attaches itself to a running container.
3. The runner prepares a script (the combination ofbefore_script,script, andafter_script).
4. The runner sends the script to the container’s shellstdinand receives the output.

To override the entrypoint of a Docker image, define an emptyentrypointin the.gitlab-ci.ymlfile, 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, theentrypointcan be set to an empty value.
• For Docker 17.03 and earlier, theentrypointcan be set to/bin/sh -c,/bin/bash -c, or an equivalent shell available in the image.

The syntax ofimage:entrypointis similar toDockerfile’sENTRYPOINT.

Let’s assume you have asuper/sql:experimentalimage 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 runas 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 onsuper/sql:experimental.
• Setting theENTRYPOINTto a shell.
• Using the new image in your CI job.

You can now define anentrypointin the.gitlab-ci.ymlfile.

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 inconfig.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, seethe relevant Docker documentation.
• Credential Helpers. For more information, seethe relevant Docker documentation.

To define which option should be used, the runner process reads the configuration in this order:

• ADOCKER_AUTH_CONFIGCI/CD variable.
• ADOCKER_AUTH_CONFIGenvironment variable set in the runner’sconfig.tomlfile.
• Aconfig.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 forKubernetes executorin GitLab Runner 13.1 and later.
• Credentials StoreandCredential Helpersrequire 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 variableDOCKER_AUTH_CONFIGwith appropriate authentication information.

1. Per-job: To configure one job to access a private registry, addDOCKER_AUTH_CONFIGas aCI/CD variable.
2. Per-runner: To configure a runner so all its jobs can access a private registry, addDOCKER_AUTH_CONFIGas an environment variable in the runner’s configuration.