Skip to content
Snippets Groups Projects

Merge Requests - Assignee

Closed gitlab-qa-bot requested to merge master into 11-0-stable
4 files
+ 93
45
Compare changes
  • Side-by-side
  • Inline
Files
4
@@ -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
Loading