Merge branch 'strausmann-master-patch-04833' into 'master'

Include more helpful snippets for Composer packages

See merge request gitlab-org/gitlab!44060

doc/user/packages/composer_repository/index.md

@@ -33,9 +33,16 @@ can be any public or private repository.
    ```json
    {
      "name": "<namespace>/composer-test",
+     "description": "Library XY",
      "type": "library",
      "license": "GPL-3.0-only",
-     "version": "1.0.0"
+     "authors": [
+        {
+            "name": "John Doe",
+            "email": "john@example.com"
+        }
+     ],
+     "require": {}
    }
    ```
 
@@ -61,6 +68,8 @@ so that anyone who can access the project can use the package as a dependency.
 Prerequisites:
 
 - 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`.
 
@@ -124,8 +133,8 @@ Install a package from the Package Registry so you can use it as a dependency.
 Prerequisites:
 
 - 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 `api`.
+- 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`.
 
   NOTE: **Note:**
   [Deploy tokens](./../../project/deploy_tokens/index.md) are
@@ -135,12 +144,30 @@ To install a package:
 
 1. Add the Package Registry URL to your project's `composer.json` file, along with the package name and version you want to install:
 
+   - Connect to the Package Registry for your group:
+
+   ```shell
+   composer config repositories.<group_id> composer https://gitlab.example.com/api/v4/group/<group_id>/-/packages/composer/
+   ```
+
+   - Set the required package version:
+
+   ```shell 
+   composer require <package_name>:<version>
+   ```
+
+   Result in the `composer.json` file:
+
    ```json
    {
      ...
-     "repositories": [
-       { "type": "composer", "url": "https://gitlab.example.com/api/v4/group/<group_id>/-/packages/composer/packages.json" }
-     ],
+     "repositories": {
+       "<group_id>": {
+         "type": "composer",
+         "url": "https://gitlab.example.com/api/v4/group/<group_id>/-/packages/composer/"
+       },
+       ...
+     },
      "require": {
        ...
        "<package_name>": "<version>"
@@ -149,6 +176,12 @@ To install a package:
    }
    ```
 
+   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.
@@ -159,6 +192,64 @@ To install a package:
    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:**