Add the ways needed to authenticate to the registry via CI/CD

parent df0b8b94
......@@ -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
......
......@@ -45,16 +45,14 @@ the following table.
| Scope | Description |
| ----- | ----------- |
|`read_user` | Allows access to the read-only endpoints under `/users`. Essentially, any of the `GET` requests in the [Users API][users] are allowed ([introduced][ce-5951] in GitLab 8.15). |
| `api` | Grants complete access to the API (read/write) ([introduced][ce-5951] in GitLab 8.15). Required for accessing Git repositories over HTTP when 2FA is enabled. |
| `read_registry` | Allows to read [container registry] images if a project is private and authorization is required ([introduced][ce-11845] in GitLab 9.3). |
| `api` | Grants complete access to the API and Container Registry (read/write) ([introduced](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/5951) in GitLab 8.15). Required for accessing Git repositories over HTTP when 2FA is enabled. |
| `read_registry` | Allows to read (pull) [container registry] images if a project is private and authorization is required ([introduced](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/11845) in GitLab 9.3). |
| `sudo` | Allows performing API actions as any user in the system (if the authenticated user is an admin) ([introduced][ce-14838] in GitLab 10.2). |
| `read_repository` | Allows read-access to the repository through git clone. |
| `read_repository` | Allows read-access (pull) to the repository through git clone. |
[2fa]: ../account/two_factor_authentication.md
[api]: ../../api/README.md
[ce-3749]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/3749
[ce-5951]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/5951
[ce-11845]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/11845
[ce-14838]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/14838
[container registry]: ../project/container_registry.md
[users]: ../../api/users.md
......
......@@ -119,12 +119,17 @@ and [Using the GitLab Container Registry documentation](../../ci/docker/using_do
> Project Deploy Tokens were [introduced][ce-17894] in GitLab 10.7
If a project is private, credentials will need to be provided for authorization.
The preferred way to do this, is either by using a [personal access tokens][pat] or a [project deploy token][pdt].
There are two ways to do this:
- By using a [personal access token](../profile/personal_access_tokens.md).
- By using a [deploy token](../project/deploy_tokens/index.md).
The minimal scope needed for both of them is `read_registry`.
Example of using a personal access token:
```
docker login registry.example.com -u <your_username> -p <your_access_token>
Example of using a token:
```sh
docker login registry.example.com -u <username> -p <token>
```
## Troubleshooting the GitLab Container Registry
......
......@@ -9,7 +9,7 @@ at midnight UTC and that they can be only managed by [maintainers](https://docs.
## Creating a Deploy Token
You can create as many deploy tokens as you like from the settings of your project:
You can create as many deploy tokens as you like from the settings of your project:
1. Log in to your GitLab account.
1. Go to the project you want to create Deploy Tokens for.
......@@ -49,14 +49,13 @@ To download a repository using a Deploy Token, you just need to:
2. Take note of your `username` and `token`
3. `git clone` the project using the Deploy Token:
```sh
git clone http://<username>:<deploy_token>@gitlab.example.com/tanuki/awesome_project.git
```
```bash
git clone https://<username>:<deploy_token>@gitlab.example.com/tanuki/awesome_project.git
```
Just replace `<username>` and `<deploy_token>` with the proper values
Replace `<username>` and `<deploy_token>` with the proper values.
### Read container registry images
### Read Container Registry images
To read the container registry images, you'll need to:
......@@ -64,21 +63,29 @@ To read the container registry images, you'll need to:
2. Take note of your `username` and `token`
3. Log in to GitLab’s Container Registry using the deploy token:
```
```sh
docker login registry.example.com -u <username> -p <deploy_token>
```
Just replace `<username>` and `<deploy_token>` with the proper values. Then you can simply
Just replace `<username>` and `<deploy_token>` with the proper values. Then you can simply
pull images from your Container Registry.
### GitLab Deploy Token
> [Introduced][ce-18414] in GitLab 10.8.
There's a special case when it comes to Deploy Tokens, if a user creates one
named `gitlab-deploy-token`, the username and token of the Deploy Token will be
automatically exposed to the CI/CD jobs as environment variables: `CI_DEPLOY_USER` and
`CI_DEPLOY_PASSWORD`, respectively.
There's a special case when it comes to Deploy Tokens. If a user creates one
named `gitlab-deploy-token`, the username and token of the Deploy Token will be
automatically exposed to the CI/CD jobs as environment variables: `CI_DEPLOY_USER` and
`CI_DEPLOY_PASSWORD`, respectively. With the GitLab Deploy Token, the
`read_registry` scope is implied.
After you create the token, you can login to the Container Registry using
those variables:
```sh
docker login -u $CI_DEPLOY_USER -p $CI_DEPLOY_PASSWORD $CI_REGISTRY
```
[ce-17894]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/17894
[ce-11845]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/11845
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment