diff options
Diffstat (limited to 'doc/ci/docker/using_docker_build.md')
-rw-r--r-- | doc/ci/docker/using_docker_build.md | 73 |
1 files changed, 50 insertions, 23 deletions
diff --git a/doc/ci/docker/using_docker_build.md b/doc/ci/docker/using_docker_build.md index 63338ff632c..7238c11dc47 100644 --- a/doc/ci/docker/using_docker_build.md +++ b/doc/ci/docker/using_docker_build.md @@ -394,8 +394,56 @@ If you're running multiple Runners you will have to modify all configuration fil login to GitLab's Container Registry. Once you've built a Docker image, you can push it up to the built-in -[GitLab Container Registry](../../user/project/container_registry.md). For example, -if you're using docker-in-docker on your runners, this is how your `.gitlab-ci.yml` +[GitLab Container Registry](../../user/project/container_registry.md). +Some things you should be aware of: + +- You must [log in to the container registry](#authenticating-to-the-container-registry) + before running commands. You can do this in the `before_script` if multiple + jobs depend on it. +- Using `docker build --pull` makes sure that Docker fetches any changes to base + images before building just in case your cache is stale. It takes slightly + longer, but means you don’t get stuck without security patches to base images. +- Doing an explicit `docker pull` before each `docker run` makes sure to fetch + the latest image that was just built. This is especially important if you are + using multiple runners that cache images locally. Using the git SHA in your + image tag makes this less necessary since each job will be unique and you + shouldn't ever have a stale image, but it's still possible if you re-build a + given commit after a dependency has changed. +- You don't want to build directly to `latest` in case there are multiple jobs + happening simultaneously. + +### Authenticating to the Container Registry + +There are 3 ways to authenticate to the Container Registry: + +- **Using the special `gitlab-ci-token` user**: This user is created for you in order to + push to the Registry connected to your project. Its password is provided in the + `$CI_JOB_TOKEN` variable. This allows you to automate building and deployment + of your Docker images and has read and write access to the registry. + This is ephemeral, so it's only valid for one job: + + ```sh + docker login -u gitlab-ci-token -p $CI_JOB_TOKEN $CI_REGISTRY + ``` + +- **Using a personal access token**: A [personal access token](../../user/profile/personal_access_tokens.md) + can be used in case your project is private. For read access, the scope + should be `read_registry`. For read/write access, use `api`: + + ```sh + docker login -u <username> -p <access_token> $CI_REGISTRY + ``` + +- **Using a deploy token**: A special [deploy token](../../user/project/deploy_tokens/index.md#gitlab-deploy-token) + can be used for usage with private projects. It provides read-only access: + + ```sh + docker login -u $CI_DEPLOY_USER -p $CI_DEPLOY_PASSWORD $CI_REGISTRY + ``` + +### Container Registry examples + +If you're using docker-in-docker on your Runners, this is how your `.gitlab-ci.yml` could look like: ```yaml @@ -413,11 +461,6 @@ could look like: - docker push registry.example.com/group/project/image:latest ``` -You have to use the special `gitlab-ci-token` user created for you in order to -push to the Registry connected to your project. Its password is provided in the -`$CI_JOB_TOKEN` variable. This allows you to automate building and deployment -of your Docker images. - You can also make use of [other variables](../variables/README.md) to avoid hardcoding: ```yaml @@ -507,22 +550,6 @@ deploy: - master ``` -Some things you should be aware of when using the Container Registry: - -- You must log in to the container registry before running commands. Putting - this in `before_script` will run it before each job. -- Using `docker build --pull` makes sure that Docker fetches any changes to base - images before building just in case your cache is stale. It takes slightly - longer, but means you don’t get stuck without security patches to base images. -- Doing an explicit `docker pull` before each `docker run` makes sure to fetch - the latest image that was just built. This is especially important if you are - using multiple runners that cache images locally. Using the git SHA in your - image tag makes this less necessary since each job will be unique and you - shouldn't ever have a stale image, but it's still possible if you re-build a - given commit after a dependency has changed. -- You don't want to build directly to `latest` in case there are multiple jobs - happening simultaneously. - [docker-in-docker]: https://blog.docker.com/2013/09/docker-can-now-run-within-docker/ [docker-cap]: https://docs.docker.com/engine/reference/run/#runtime-privilege-and-linux-capabilities [2fa]: ../../user/profile/account/two_factor_authentication.md |