diff options
| -rw-r--r-- | doc/ci/docker/using_docker_build.md | 84 | ||||
| -rw-r--r-- | doc/user/profile/personal_access_tokens.md | 8 | ||||
| -rw-r--r-- | doc/user/project/container_registry.md | 13 | ||||
| -rw-r--r-- | doc/user/project/deploy_tokens/index.md | 33 |
4 files changed, 93 insertions, 45 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 diff --git a/doc/user/profile/personal_access_tokens.md b/doc/user/profile/personal_access_tokens.md index 25d6c34409c..7d55048c994 100644 --- a/doc/user/profile/personal_access_tokens.md +++ b/doc/user/profile/personal_access_tokens.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 diff --git a/doc/user/project/container_registry.md b/doc/user/project/container_registry.md index 2709ebb6f05..1b1827a2658 100644 --- a/doc/user/project/container_registry.md +++ b/doc/user/project/container_registry.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 diff --git a/doc/user/project/deploy_tokens/index.md b/doc/user/project/deploy_tokens/index.md index ff647b2f0a2..dc73194309c 100644 --- a/doc/user/project/deploy_tokens/index.md +++ b/doc/user/project/deploy_tokens/index.md @@ -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 |