diff options
Diffstat (limited to 'doc/ci/docker/using_docker_build.md')
| -rw-r--r-- | doc/ci/docker/using_docker_build.md | 84 |
1 files changed, 61 insertions, 23 deletions
diff --git a/doc/ci/docker/using_docker_build.md b/doc/ci/docker/using_docker_build.md index 0b64c8caba7..3b41036cd14 100644 --- a/doc/ci/docker/using_docker_build.md +++ b/doc/ci/docker/using_docker_build.md @@ -395,8 +395,67 @@ 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` 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` fetches + 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. However, it's still possible to have a + stale image if you re-build a given commit after a dependency has changed. +- You don't want to build directly to `latest` tag in case there are multiple jobs + happening simultaneously. + +### Authenticating to the Container Registry + +There are three ways to authenticate to the Container Registry via GitLab CI/CD +and depend on the visibility of your project. + +For all projects, mostly suitable for public ones: + +- **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 automatically + set with the `$CI_JOB_TOKEN` variable. This allows you to automate building and deploying + your Docker images and has read/write access to the Registry. This is ephemeral, + so it's only valid for one job. You can use the following example as-is: + + ```sh + docker login -u gitlab-ci-token -p $CI_JOB_TOKEN $CI_REGISTRY + ``` + +For private and internal projects: + +- **Using a personal access token**: You can create and use a + [personal access token](../../user/profile/personal_access_tokens.md) + in case your project is private: + - For read (pull) access, the scope should be `read_registry`. + - For read/write (pull/push) access, use `api`. + Replace the `<username>` and `<access_token>` in the following example: + + ```sh + docker login -u <username> -p <access_token> $CI_REGISTRY + ``` + +- **Using the GitLab Deploy Token**: You can create and use a + [special deploy token](../../user/project/deploy_tokens/index.md#gitlab-deploy-token) + with your private projects. It provides read-only (pull) access to the Registry. + Once created, you can use the special environment variables, and GitLab CI/CD + will fill them in for you. You can use the following example as-is: + + ```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 @@ -414,11 +473,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 @@ -508,22 +562,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 |