Add latest changes from gitlab-org/gitlab@13-5-stable-eev13.5.0-rc42

2 files changed, 201 insertions, 114 deletions

diff --git a/doc/user/packages/composer_repository/img/project_id_v13_5.png b/doc/user/packages/composer_repository/img/project_id_v13_5.png
new file mode 100644
index 00000000000..45861b6ff1b
--- /dev/null
+++ b/doc/user/packages/composer_repository/img/project_id_v13_5.png
diff --git a/doc/user/packages/composer_repository/index.md b/doc/user/packages/composer_repository/index.md
index 89e02b4847c..d4fb662c3a6 100644
--- a/doc/user/packages/composer_repository/index.md
+++ b/doc/user/packages/composer_repository/index.md
@@ -4,172 +4,259 @@ group: Package
 info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers
 ---
 
-# GitLab Composer Repository
+# Composer packages in the Package Registry
 
 > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/15886) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.2.
 > - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/221259) to GitLab Core in 13.3.
 
-With the GitLab Composer Repository, every project can have its own space to store [Composer](https://getcomposer.org/) packages.
+Publish [Composer](https://getcomposer.org/) packages in your project's Package Registry.
+Then, install the packages whenever you need to use them as a dependency.
 
-## Enabling the Composer Repository
+Only Composer 1.x is supported. Consider contributing or even adding support for
+[Composer 2.0 in the Package Registry](https://gitlab.com/gitlab-org/gitlab/-/issues/259840).
 
-NOTE: **Note:**
-This option is available only if your GitLab administrator has
-[enabled support for the Package Registry](../../../administration/packages/index.md).
+## Create a Composer package
 
-When the Composer Repository is enabled, it is available for all new projects
-by default. To enable it for existing projects, or if you want to disable it:
+If you do not have a Composer package, create one and check it in to
+a repository. This example shows a GitLab repository, but the repository
+can be any public or private repository.
 
-1. Navigate to your project's **Settings > General > Visibility, project features, permissions**.
-1. Find the Packages feature and enable or disable it.
-1. Click on **Save changes** for the changes to take effect.
+1. Create a directory called `my-composer-package` and change to that directory:
 
-You should then be able to see the **Packages & Registries** section on the left sidebar.
+   ```shell
+   mkdir my-composer-package && cd my-composer-package
+   ```
 
-## Getting started
+1. Run [`composer init`](https://getcomposer.org/doc/03-cli.md#init) and answer the prompts.
 
-This section covers creating a new example Composer package to publish. This is a
-quickstart to test out the **GitLab Composer Registry**.
+   For namespace, enter your unique [namespace](../../../user/group/index.md#namespaces), like your GitLab username or group name.
 
-To complete this section, you need a recent version of [Composer](https://getcomposer.org/).
+   A file called `composer.json` is created:
 
-### Creating a package project
+   ```json
+   {
+     "name": "<namespace>/composer-test",
+     "description": "Library XY",
+     "type": "library",
+     "license": "GPL-3.0-only",
+     "authors": [
+        {
+            "name": "John Doe",
+            "email": "john@example.com"
+        }
+     ],
+     "require": {}
+   }
+   ```
 
-Understanding how to create a full Composer project is outside the scope of this
-guide, but you can create a small package to test out the registry. Start by
-creating a new directory called `my-composer-package`:
+1. Run Git commands to tag the changes and push them to your repository:
 
-```shell
-mkdir my-composer-package && cd my-composer-package
-```
+   ```shell
+   git init
+   git add composer.json
+   git commit -m 'Composer package test'
+   git tag v1.0.0
+   git remote add origin git@gitlab.example.com:<namespace>/<project-name>.git
+   git push --set-upstream origin master
+   git push origin v1.0.0
+   ```
 
-Create a new `composer.json` file inside this directory to set up the basic project:
+The package is now in your GitLab Package Registry.
 
-```shell
-touch composer.json
-```
+## Publish a Composer package by using the API
 
-Inside `composer.json`, add the following code:
+Publish a Composer package to the Package Registry,
+so that anyone who can access the project can use the package as a dependency.
 
-```json
-{
-  "name": "<namespace>/composer-test",
-  "type": "library",
-  "license": "GPL-3.0-only",
-  "version": "1.0.0"
-}
-```
+Prerequisites:
 
-Replace `<namespace>` with a unique namespace like your GitLab username or group name.
+- A package in a GitLab repository.
+- A valid `composer.json` file.
+- The Packages feature is enabled in a GitLab repository.
+- The project ID, which is on the project's home page.
+- A [personal access token](../../../user/profile/personal_access_tokens.md) with the scope set to `api`.
 
-After this basic package structure is created, we need to tag it in Git and push it to the repository.
+  NOTE: **Note:**
+  [Deploy tokens](./../../project/deploy_tokens/index.md) are
+  [not yet supported](https://gitlab.com/gitlab-org/gitlab/-/issues/240897) for use with Composer.
 
-```shell
-git init
-git add composer.json
-git commit -m 'Composer package test'
-git tag v1.0.0
-git remote add origin git@gitlab.com:<namespace>/<project-name>.git
-git push --set-upstream origin master
-git push origin v1.0.0
-```
+To publish the package:
 
-### Publishing the package
+- Send a `POST` request to the [Packages API](../../../api/packages.md).
 
-Now that the basics of our project is completed, we can publish the package.
-To publish the package, you need:
+  For example, you can use `curl`:
 
-- A personal access token or `CI_JOB_TOKEN`.
+  ```shell
+  curl --data tag=<tag> "https://__token__:<personal-access-token>@gitlab.example.com/api/v4/projects/<project_id>/packages/composer"
+  ```
 
-  ([Deploy tokens](./../../project/deploy_tokens/index.md) are not yet supported for use with Composer.)
+  - `<personal-access-token>` is your personal access token.
+  - `<project_id>` is your project ID.
+  - `<tag>` is the Git tag name of the version you want to publish.
+     To publish a branch, use `branch=<branch>` instead of `tag=<tag>`.
 
-- Your project ID which can be found on the home page of your project.
+You can view the published package by going to **Packages & Registries > Package Registry** and
+selecting the **Composer** tab.
 
-To publish the package hosted on GitLab, make a `POST` request to the GitLab package API.
-A tool like `curl` can be used to make this request:
+## Publish a Composer package by using CI/CD
 
-You can generate a [personal access token](../../../user/profile/personal_access_tokens.md) with the scope set to `api` for repository authentication. For example:
+You can publish a Composer package to the Package Registry as part of your CI/CD process.
 
-```shell
-curl --data tag=<tag> 'https://__token__:<personal-access-token>@gitlab.com/api/v4/projects/<project_id>/packages/composer'
-```
+1. Specify a `CI_JOB_TOKEN` in your `.gitlab-ci.yml` file:
 
-Where:
+   ```yaml
+   stages:
+     - deploy
 
-- `<personal-access-token>` is your personal access token.
-- `<project_id>` is your project ID.
-- `<tag>` is the Git tag name of the version you want to publish. In this example it should be `v1.0.0`. Notice that instead of `tag=<tag>` you can also use `branch=<branch>` to publish branches.
+   deploy:
+     stage: deploy
+     script:
+       - 'curl --header "Job-Token: $CI_JOB_TOKEN" --data tag=<tag> "https://gitlab.example.com/api/v4/projects/$CI_PROJECT_ID/packages/composer"'
+   ```
 
-If the above command succeeds, you now should be able to see the package under the **Packages & Registries** section of your project page.
+1. Run the pipeline.
 
-### Publishing the package with CI/CD
+You can view the published package by going to **Packages & Registries > Package Registry** and selecting the **Composer** tab.
 
-To work with Composer commands within [GitLab CI/CD](./../../../ci/README.md), you can
-publish Composer packages by using `CI_JOB_TOKEN` in your `.gitlab-ci.yml` file:
+### Use a CI/CD template
 
-```yaml
-stages:
-  - deploy
+A more detailed Composer CI/CD file is also available as a `.gitlab-ci.yml` template:
 
-deploy:
-  stage: deploy
-  script:
-    - 'curl --header "Job-Token: $CI_JOB_TOKEN" --data tag=<tag> "https://gitlab.example.com/api/v4/projects/$CI_PROJECT_ID/packages/composer"'
-```
+1. On the left sidebar, click **Project overview**.
+1. Above the file list, click **Set up CI/CD**. If this button is not available, select **CI/CD Configuration** and then **Edit**.
+1. From the **Apply a template** list, select **Composer**.
 
-### Installing a package
+CAUTION: **Warning:**
+Do not save unless you want to overwrite the existing CI/CD file.
 
-To install your package, you need:
+## Install a Composer package
 
-- A personal access token. You can generate a [personal access token](../../../user/profile/personal_access_tokens.md) with the scope set to `api` for repository authentication.
-- Your group ID which can be found on the home page of your project's group.
+Install a package from the Package Registry so you can use it as a dependency.
 
-Add the GitLab Composer package repository to your existing project's `composer.json` file, along with the package name and version you want to install like so:
+Prerequisites:
 
-```json
-{
-  ...
-  "repositories": [
-    { "type": "composer", "url": "https://gitlab.com/api/v4/group/<group_id>/-/packages/composer/packages.json" }
-  ],
-  "require": {
-    ...
-    "<package_name>": "<version>"
-  },
-  ...
-}
-```
+- A package in the Package Registry.
+- The group ID, which is on the group's home page.
+- A [personal access token](../../../user/profile/personal_access_tokens.md) with the scope set to, at minimum, `read_api`.
 
-Where:
+  NOTE: **Note:**
+  [Deploy tokens](./../../project/deploy_tokens/index.md) are
+  [not yet supported](https://gitlab.com/gitlab-org/gitlab/-/issues/240897) for use with Composer.
 
-- `<group_id>` is the group ID found under your project's group page.
-- `<package_name>` is your package name as defined in your package's `composer.json` file.
-- `<version>` is your package version (`1.0.0` in this example).
+To install a package:
 
-You also need to create a `auth.json` file with your GitLab credentials:
+1. Add the Package Registry URL to your project's `composer.json` file, along with the package name and version you want to install:
 
-```json
-{
-    "gitlab-token": {
-       "gitlab.com": "<personal_access_token>"
-    }
-}
-```
+   - Connect to the Package Registry for your group:
 
-Where:
+   ```shell
+   composer config repositories.<group_id> composer https://gitlab.example.com/api/v4/group/<group_id>/-/packages/composer/
+   ```
 
-- `<personal_access_token>` is your personal access token.
+   - Set the required package version:
 
-With the `composer.json` and `auth.json` files configured, you can install the package by running `composer`:
+   ```shell
+   composer require <package_name>:<version>
+   ```
 
-```shell
-composer update
-```
+   Result in the `composer.json` file:
 
-If successful, you should be able to see the output indicating that the package has been successfully installed.
+   ```json
+   {
+     ...
+     "repositories": {
+       "<group_id>": {
+         "type": "composer",
+         "url": "https://gitlab.example.com/api/v4/group/<group_id>/-/packages/composer/"
+       },
+       ...
+     },
+     "require": {
+       ...
+       "<package_name>": "<version>"
+     },
+     ...
+   }
+   ```
+
+   You can unset this with the command:
+
+   ```shell
+   composer config --unset repositories.<group_id>
+   ```
+
+   - `<group_id>` is the group ID.
+   - `<package_name>` is the package name defined in your package's `composer.json` file.
+   - `<version>` is the package version.
+
+1. Create an `auth.json` file with your GitLab credentials:
+
+   ```shell
+   composer config gitlab-token.<DOMAIN-NAME> <personal_access_token>
+   ```
+
+   Result in the `auth.json` file:
+
+   ```json
+   {
+     ...
+     "gitlab-token": {
+       "<DOMAIN-NAME>": "<personal_access_token>",
+       ...
+     }
+   }
+   ```
+
+   You can unset this with the command:
+
+   ```shell
+   composer config --unset --auth gitlab-token.<DOMAIN-NAME>
+   ```
+
+   - `<DOMAIN-NAME>` is the GitLab instance URL `gitlab.com` or `gitlab.example.com`.
+   - `<personal_access_token>` with the scope set to `read_api`.
+
+1. If you are on a GitLab self-managed instance, add `gitlab-domains` to `composer.json`.
+
+   ```shell
+   composer config gitlab-domains gitlab01.example.com gitlab02.example.com
+   ```
+
+   Result in the `composer.json` file:
+
+   ```json
+   {
+     ...
+     "repositories": [
+       { "type": "composer", "url": "https://gitlab.example.com/api/v4/group/<group_id>/-/packages/composer/" }
+     ],
+     "config": {
+       ...
+       "gitlab-domains": ["gitlab01.example.com", "gitlab02.example.com"]
+     },
+     "require": {
+       ...
+       "<package_name>": "<version>"
+     },
+     ...
+   }
+   ```
+
+   You can unset this with the command:
+
+   ```shell
+   composer config --unset gitlab-domains
+   ```
+
+   NOTE: **Note:**
+   On GitLab.com, Composer uses the GitLab token from `auth.json` as a private token by default.
+   Without the `gitlab-domains` definition in `composer.json`, Composer uses the GitLab token
+   as basic-auth, with the token as a username and a blank password. This results in a 401 error.
+
+Output indicates that the package has been successfully installed.
 
 CAUTION: **Important:**
-Make sure to never commit the `auth.json` file to your repository. To install packages from a CI job,
+Never commit the `auth.json` file to your repository. To install packages from a CI/CD job,
 consider using the [`composer config`](https://getcomposer.org/doc/articles/handling-private-packages-with-satis.md#authentication) tool with your personal access token
 stored in a [GitLab CI/CD environment variable](../../../ci/variables/README.md) or in
-[Hashicorp Vault](../../../ci/secrets/index.md).
+[HashiCorp Vault](../../../ci/secrets/index.md).