Revamp of Container Registry topics

Related to: https://gitlab.com/gitlab-org/gitlab/-/issues/247950

doc/ci/docker/using_docker_build.md

@@ -503,7 +503,7 @@ and [using the OverlayFS storage driver](https://docs.docker.com/engine/userguid
 ## Using the GitLab Container Registry
 
 Once you've built a Docker image, you can push it up to the built-in
-[GitLab Container Registry](../../user/packages/container_registry/index.md#build-and-push-images-using-gitlab-cicd).
+[GitLab Container Registry](../../user/packages/container_registry/index.md#build-and-push-by-using-gitlab-cicd).
 
 ## Troubleshooting
 

doc/development/architecture.md

@@ -620,7 +620,7 @@ Redis is packaged to provide a place to store:
   - [Source](../administration/packages/container_registry.md#enable-the-container-registry)
   - [GDK](https://gitlab.com/gitlab-org/gitlab-development-kit/blob/master/doc/howto/registry.md)
 - Layer: Core Service (Processor)
-- GitLab.com: [GitLab Container Registry](../user/packages/container_registry/index.md#build-and-push-images-using-gitlab-cicd)
+- GitLab.com: [GitLab Container Registry](../user/packages/container_registry/index.md#build-and-push-by-using-gitlab-cicd)
 
 The registry is what users use to store their own Docker images. The bundled
 registry uses NGINX as a load balancer and GitLab as an authentication manager.

doc/development/telemetry/usage_ping.md

@@ -650,7 +650,7 @@ build in a [downstream pipeline of the `omnibus-gitlab-mirror` project](https://
 1. In the downstream pipeline, wait for the `gitlab-docker` job to finish.
 1. Open the job logs and locate the full container name including the version. It will take the following form: `registry.gitlab.com/gitlab-org/build/omnibus-gitlab-mirror/gitlab-ee:<VERSION>`.
 1. On your local machine, make sure you are logged in to the GitLab Docker registry. You can find the instructions for this in
-[Authenticating to the GitLab Container Registry](../../user/packages/container_registry/index.md#authenticating-to-the-gitlab-container-registry).
+[Authenticate to the GitLab Container Registry](../../user/packages/container_registry/index.md#authenticate-with-the-container-registry).
 1. Once logged in, download the new image via `docker pull registry.gitlab.com/gitlab-org/build/omnibus-gitlab-mirror/gitlab-ee:<VERSION>`
 1. For more information about working with and running Omnibus GitLab containers in Docker, please refer to [GitLab Docker images](https://docs.gitlab.com/omnibus/docker/README.html) in the Omnibus documentation.
 

doc/user/application_security/container_scanning/index.md

@@ -43,7 +43,7 @@ To enable container scanning in your pipeline, you need the following:
   or [`kubernetes`](https://docs.gitlab.com/runner/install/kubernetes.html) executor.
 - Docker `18.09.03` or higher installed on the same computer as the runner. If you're using the
   shared runners on GitLab.com, then this is already the case.
-- [Build and push](../../packages/container_registry/index.md#container-registry-examples-with-gitlab-cicd)
+- [Build and push](../../packages/container_registry/index.md#build-and-push-by-using-gitlab-cicd)
   your Docker image to your project's container registry. The name of the Docker image should use
   the following [predefined environment variables](../../../ci/variables/predefined_variables.md):
 

doc/user/packages/container_registry/index.md

@@ -9,11 +9,11 @@ info: To determine the technical writer assigned to the Stage/Group associated w
 > - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/4040) in GitLab 8.8.
 > - Docker Registry manifest `v1` support was added in GitLab 8.9 to support Docker
 >   versions earlier than 1.10.
-> - Starting from GitLab 8.12, if you have 2FA enabled in your account, you need
->   to pass a [personal access token](../../profile/personal_access_tokens.md) instead of your password in order to
->   login to GitLab's Container Registry.
-> - Multiple level image names support was added in GitLab 9.1.
-> - The group level Container Registry was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/23315) in GitLab 12.10.
+> - Starting in GitLab 8.12, if you have [two-factor authentication](../../profile/account/two_factor_authentication.md) enabled in your account, you need
+>   to pass a [personal access token](../../profile/personal_access_tokens.md) instead of your password to
+>   sign in to the Container Registry.
+> - Support for multiple level image names was added in GitLab 9.1.
+> - The group-level Container Registry was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/23315) in GitLab 12.10.
 > - Searching by image repository name was [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/31322) in GitLab 13.0.
 
 With the Docker Container Registry integrated into GitLab, every GitLab project can
@@ -21,7 +21,6 @@ have its own space to store its Docker images.
 
 You can read more about Docker Registry at <https://docs.docker.com/registry/introduction/>.
 
-NOTE: **Note:**
 This document is the user guide. To learn how to enable the Container
 Registry for your GitLab instance, visit the
 [administrator documentation](../../../administration/packages/container_registry.md).
@@ -35,7 +34,8 @@ You can view the Container Registry for a project or group.
 
 You can search, sort, filter, and [delete](#delete-images-from-within-gitlab) containers on this page.
 
-CAUTION: **Warning:**
+Only members of the project or group can access a private project's Container Registry.
+
 If a project is public, so is the Container Registry.
 
 ## Use images from the Container Registry
@@ -58,134 +58,137 @@ To download and run a container image hosted in the GitLab Container Registry:
 For more information on running Docker containers, visit the
 [Docker documentation](https://docs.docker.com/engine/userguide/intro/).
 
-## Authenticating to the GitLab Container Registry
+## Image naming convention
+
+Images follow this naming convention:
 
-If you visit the **Packages & Registries > Container Registry** link under your project's
-menu, you can see the explicit instructions to login to the Container Registry
-by using your GitLab credentials.
+```plaintext
+<registry URL>/<namespace>/<project>/<image>
+```
 
-For example if the Registry's URL is `registry.example.com`, then you should be
-able to log in with:
+If your project is `gitlab.example.com/mynamespace/myproject`, for example,
+then your image must be named `gitlab.example.com/mynamespace/myproject/my-app` at a mimimum.
 
-```shell
-docker login registry.example.com
+You can append additional names to the end of an image name, up to three levels deep.
+
+For example, these are all valid image names for images within the project named `myproject`:
+
+```plaintext
+registry.example.com/mynamespace/myproject:some-tag
 ```
 
-NOTE: **Note:**
-If you have [2 Factor Authentication](../../profile/account/two_factor_authentication.md)
-enabled in your account, you need to pass a
-[personal access token](../../profile/personal_access_tokens.md) instead
-of your password in order to login to GitLab's Container Registry.
+```plaintext
+registry.example.com/mynamespace/myproject/image:latest
+```
 
-Credentials must be provided for authorization to any non-public registry. Only project members can access private,
-GitLab-hosted registries.
+```plaintext
+registry.example.com/mynamespace/myproject/my/image:rc1
+```
 
-There are two ways to authenticate:
+## Build and push images by using Docker commands
 
-- By using a [personal access token](../../profile/personal_access_tokens.md).
-- By using a [deploy token](../../project/deploy_tokens/index.md).
+To build and push to the Container Registry, you can use Docker commands.
 
-The minimum scope needed for both of them is `read_registry`.
+### Authenticate with the Container Registry
 
-Example of using a token:
+Before you can build and push images, you must authenticate with the Container Registry.
 
-```shell
-docker login registry.example.com -u <username> -p <token>
-```
+To authenticate, you can use:
 
-## Build and push images from your local machine
+- A [personal access token](../../profile/personal_access_tokens.md).
+- A [deploy token](../../project/deploy_tokens/index.md).
 
-Building and publishing images should be a straightforward process. Just make
-sure that you are using the Registry URL with the namespace and project name
-that is hosted on GitLab:
+Both of these require the minimum scope to be:
 
-```shell
-docker build -t registry.example.com/group/project/image .
-docker push registry.example.com/group/project/image
-```
+- For read (pull) access, `read_registry`.
+- For write (push) access, `write_registry`.
 
-Your image is named after the following scheme:
+To authenticate, run the `docker` command. For example:
 
-```plaintext
-<registry URL>/<namespace>/<project>/<image>
-```
+   ```shell
+   docker login registry.example.com -u <username> -p <token>
+   ```
 
-GitLab supports up to three levels of image repository names.
-The following examples of image tags are valid:
+### Build and push images by using Docker commands
 
-```plaintext
-registry.example.com/group/project:some-tag
-registry.example.com/group/project/image:latest
-registry.example.com/group/project/my/image:rc1
-```
+To build and push to the Container Registry:
 
-NOTE: **Note:**
-Currently there is a soft (10GB) size restriction for
-the Container Registry on GitLab.com, as part of the [repository size limit](../../project/repository/index.md).
-
-## Build and push images using GitLab CI/CD
-
-While you can build and push your images from your local machine, take
-full advantage of the Container Registry by combining it with GitLab CI/CD.
-You can then create workflows and automate any processes that involve testing,
-building, and eventually deploying your project from the Docker image you
-created.
-
-Before diving into details, some things you should be aware of:
-
-- You must [authenticate to the container registry](#authenticating-to-the-container-registry-with-gitlab-cicd)
-  before running any 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 in case your cache is stale. It takes slightly
-  longer, but it means you don’t get stuck without security patches for 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 is 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.
+1. Authenticate with the Container Registry. 
 
-### Authenticating to the Container Registry with GitLab CI/CD
+1. Run the command to build or push. For example, to build: 
 
-There are three ways to authenticate to the Container Registry via
-[GitLab CI/CD](../../../ci/yaml/README.md):
+   ```shell
+   docker build -t registry.example.com/group/project/image .
+   ```
 
-- **Using the special `CI_REGISTRY_USER` variable**: The user specified by this variable is created for you in order to
-  push to the Registry connected to your project. Its password is automatically
-  set with the `CI_REGISTRY_PASSWORD` 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:
+   Or to push:
+
+   ```shell
+   docker push registry.example.com/group/project/image
+   ```
+
+You can also view these commands by going to your project's **Packages & Registries > Container Registry**.
+
+## Build and push by using GitLab CI/CD
+
+Use [GitLab CI/CD](../../../ci/yaml/README.md) to build and push images to the
+Container Registry. Use it to test, build, and deploy your project from the Docker
+image you created.
+
+### Authenticate by using GitLab CI/CD
+
+Before you can build and push images by using GitLab CI/CD, you must authenticate with the Container Registry.
+
+To use CI/CD to authenticate, you can use:
+
+- The `CI_REGISTRY_USER` variable.
+
+  This variable has read-write access to the Container Registry and is valid for
+  one job only. Its password is also automatically created and assigned to `CI_REGISTRY_PASSWORD`.
 
   ```shell
   docker login -u $CI_REGISTRY_USER -p $CI_REGISTRY_PASSWORD $CI_REGISTRY
   ```
 
-- **Using the GitLab Deploy Token**: You can create and use a
-  [special deploy token](../../project/deploy_tokens/index.md#gitlab-deploy-token)
-  with your projects.
-  Once created, you can use the special environment variables, and GitLab CI/CD
-  fills them in for you. You can use the following example as-is:
+- A [CI job token](../../../ci/triggers/README.md#ci-job-token).
 
   ```shell
-  docker login -u $CI_DEPLOY_USER -p $CI_DEPLOY_PASSWORD $CI_REGISTRY
+  docker login -u $CI_JOB_USER -p $CI_JOB_TOKEN $CI_REGISTRY
   ```
 
-- **Using a personal access token**: You can create and use a
-  [personal access token](../../profile/personal_access_tokens.md)
-  in case your project is private:
+- A [deploy token](../../project/deploy_tokens/index.md#gitlab-deploy-token) with the minimum scope of:
+  - For read (pull) access, `read_registry`.
+  - For write (push) access, `write_registry`.
 
-  - For read (pull) access, the scope should be `read_registry`.
-  - For write (push) access, the scope should be `write_registry`.
+  ```shell
+  docker login -u $CI_DEPLOY_USER -p $CI_DEPLOY_PASSWORD $CI_REGISTRY
+  ```
 
-  Replace the `<username>` and `<access_token>` in the following example:
+- A [personal access token](../../profile/personal_access_tokens.md) with the minimum scope of:
+  - For read (pull) access, `read_registry`.
+  - For write (push) access, `write_registry`.
 
   ```shell
   docker login -u <username> -p <access_token> $CI_REGISTRY
   ```
 
+### Configure your `.gitlab-ci.yml` file
+
+You can configure your `.gitlab-ci.yml` file to build and push images to the Container Registry.
+
+- If multiple jobs require authentication, put the authentication command in the `before_script`.
+- Before building, use `docker build --pull` to fetch changes to base images. It takes slightly
+  longer, but it ensures your image is up-to-date.
+- Before each `docker run`, do an explicit `docker pull` to fetch
+  the image that was just built. This is especially important if you are
+  using multiple runners that cache images locally.   
+
+  If you use the Git SHA in your image tag, each job is unique and you
+  should never 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.
+- Don't build directly to the `latest` tag because multiple jobs may be
+  happening simultaneously.
+
 ### Container Registry examples with GitLab CI/CD
 
 If you're using Docker-in-Docker on your runners, this is how your `.gitlab-ci.yml`