| `name` | yes, when used with any other option | 9.4 |Full name of the image to use. It should contain the Registry part if needed. |
| `entrypoint` | no | 9.4 |Command or script to execute as the container's entrypoint. It's translated to Docker's `--entrypoint` option while creating the container. The syntax is similar to [`Dockerfile`'s `ENTRYPOINT`](https://docs.docker.com/engine/reference/builder/#entrypoint) directive, where each shell token is a separate string in the array. |
| Setting | Required | Description |
|------------|----------| ----------- |
| `name` | Yes, when used with any other option. | Full name of the image. It should contain the registry part if needed. |
| `entrypoint` | No. | Command or script to execute as the container's entrypoint. It's translated to Docker's `--entrypoint` option while creating the container. The syntax is similar to [`Dockerfile`'s `ENTRYPOINT`](https://docs.docker.com/engine/reference/builder/#entrypoint) directive, where each shell token is a separate string in the array. |
### Overriding the entrypoint of an image
> Introduced in GitLab and GitLab Runner 9.4. Read more about the [extended configuration options](../docker/using_docker_images.md#extended-docker-configuration-options).
Before showing the available entrypoint override methods, let's describe
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 (default
from `Dockerfile` that may be overridden in `.gitlab-ci.yml`)
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.
1. The runner attaches itself to a running container.
1. The runner prepares a script (the combination of
1. The runner sends the script to the container's shell `stdin` and receives the
output.
To override the entrypoint of a Docker image, you should
define an empty `entrypoint` in `.gitlab-ci.yml`, so the runner does not start
a useless shell layer. However, that does not work for all Docker versions, and
you should check which one your runner is using:
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.
-_If Docker 17.06 or later is used,_ the `entrypoint` can be set to an empty value.
-_If Docker 17.03 or previous versions are used,_ the `entrypoint` can be set to
`/bin/sh -c`, `/bin/bash -c` or an equivalent shell available in the image.
-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`](https://docs.docker.com/engine/reference/builder/#entrypoint).
...
...
@@ -184,7 +181,7 @@ With the extended Docker configuration options, instead of:
You can now define an `entrypoint` in the `.gitlab-ci.yml` file.
**For Docker 17.06+:**
**For Docker 17.06 and later:**
```yaml
image:
...
...
@@ -192,7 +189,7 @@ image:
entrypoint:[""]
```
**For Docker =< 17.03:**
**For Docker 17.03 and earlier:**
```yaml
image:
...
...
@@ -217,40 +214,38 @@ that runner.
To access private container registries, the GitLab Runner process can use:
-[Statically defined credentials](#using-statically-defined-credentials). That is, a username and password for a specific registry.
-[Credentials Store](#use-a-credentials-store). For more information, read[the relevant Docker documentation](https://docs.docker.com/engine/reference/commandline/login/#credentials-store).
-[Credential Helpers](#use-credential-helpers). For more information, read[the relevant Docker documentation](https://docs.docker.com/engine/reference/commandline/login/#credential-helpers).
-[Statically defined credentials](#use-statically-defined-credentials). That is, a username and password for a specific registry.
-[Credentials Store](#use-a-credentials-store). For more information, see[the relevant Docker documentation](https://docs.docker.com/engine/reference/commandline/login/#credentials-store).
-[Credential Helpers](#use-credential-helpers). For more information, see[the relevant Docker documentation](https://docs.docker.com/engine/reference/commandline/login/#credential-helpers).
To define which should be used, the GitLab Runner process reads the configuration in the following order:
To define which option should be used, the runner process reads the configuration in this order:
-`DOCKER_AUTH_CONFIG` variable provided as either:
- A [CI/CD variable](../variables/README.md) in `.gitlab-ci.yml`.
- A project's variables stored on the projects **Settings > CI/CD** page.
-`DOCKER_AUTH_CONFIG` variable provided as environment variable in `config.toml` of the runner.
-`config.json` file placed in `$HOME/.docker` directory of the user running GitLab Runner process.
If the `--user` flag is provided to run the GitLab Runner child processes as unprivileged user,
the home directory of the main GitLab Runner process user is used.
-A `DOCKER_AUTH_CONFIG` variable provided as either:
- A [CI/CD variable](../variables/README.md) in the `.gitlab-ci.yml` file.
- A project's variables stored on the project's **Settings > CI/CD** page.
-A `DOCKER_AUTH_CONFIG` variable provided as environment variable 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.
GitLab Runner reads this configuration **only** from `config.toml` and ignores it if
it's provided as an environment variable. This is because GitLab Runner uses **only**
`config.toml` configuration and does not interpolate **any**environment variables at
The runner reads this configuration **only** from the `config.toml` file and ignores it if
it's provided as a CI/CD variable. This is because the runner uses **only**
`config.toml` configuration and does not interpolate **any**CI/CD variables at
runtime.
### Requirements and limitations
- This feature requires GitLab Runner **1.8** or higher.
- For GitLab Runner versions **>= 0.6, <1.8** there was a partial
support for using private registries, which required manual configuration
of credentials on runner's host. We recommend to upgrade your runner to
at least version **1.8** if you want to use private registries.
- Available for [Kubernetes executor](https://docs.gitlab.com/runner/executors/kubernetes.html)
in GitLab Runner 13.1 and later.
-[Credentials Store](#use-a-credentials-store) and [Credential Helpers](#use-credential-helpers) require binaries to be added to the GitLab Runner's `$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.
-[Credentials Store](#use-a-credentials-store) and [Credential Helpers](#use-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.
### Using statically-defined credentials
### Use statically-defined credentials
There are two approaches that you can take in order to access a
private registry. Both require setting the environment variable
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
...
...
@@ -261,7 +256,7 @@ private registry. Both require setting the environment variable
See below for examples of each.
#### Determining your `DOCKER_AUTH_CONFIG` data
#### Determine your `DOCKER_AUTH_CONFIG` data
As an example, let's assume you want to use the `registry.example.com:5000/private/image:latest`
image. This image is private and requires you to sign in to a private container
...
...
@@ -292,7 +287,7 @@ Use one of the following methods to determine the value of `DOCKER_AUTH_CONFIG`:
docker logout registry.example.com:5000
```
- In some setups, it's possible that Docker client uses the available system key
- In some setups, it's possible the Docker client uses the available system key
store to store the result of `docker login`. In that case, it's impossible to
read `~/.docker/config.json`, so you must prepare the required
base64-encoded version of `${username}:${password}` and create the Docker
...
...
@@ -318,7 +313,7 @@ Use one of the following methods to determine the value of `DOCKER_AUTH_CONFIG`:
}
```
#### Configuring a job
#### Configure a job
To configure a single job with access for `registry.example.com:5000`,
follow these steps:
...
...
@@ -337,7 +332,7 @@ follow these steps:
```
1. You can now use any private image from `registry.example.com:5000` defined in
`image`and/or `services` in your `.gitlab-ci.yml` file:
`image` or `services` in your `.gitlab-ci.yml` file:
