Merge branch 'selhorn-composer-redo' into 'master'

Docs: Revamp Composer topic

See merge request gitlab-org/gitlab!42764

doc/user/packages/composer_repository/index.md

@@ -4,172 +4,165 @@ 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
+## Create a Composer package
 
-NOTE: **Note:**
-This option is available only if your GitLab administrator has
-[enabled support for the Package Registry](../../../administration/packages/index.md).
+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.
 
-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:
+1. Create a directory called `my-composer-package` and change to that directory:
 
-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.
+   ```shell
+   mkdir my-composer-package && cd my-composer-package
+   ```
 
-You should then be able to see the **Packages & Registries** section on the left sidebar.
+1. Run [`composer init`](https://getcomposer.org/doc/03-cli.md#init) and answer the prompts. 
 
-## Getting started
+   For namespace, enter your unique [namespace](../../../user/group/index.md#namespaces), like your GitLab username or group name.
 
-This section covers creating a new example Composer package to publish. This is a
-quickstart to test out the **GitLab Composer Registry**.
+   A file called `composer.json` is created:
 
-To complete this section, you need a recent version of [Composer](https://getcomposer.org/).
-
-### Creating a package project
-
-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`:
-
-```shell
-mkdir my-composer-package && cd my-composer-package
-```
-
-Create a new `composer.json` file inside this directory to set up the basic project:
-
-```shell
-touch composer.json
-```
-
-Inside `composer.json`, add the following code:
-
-```json
-{
+   ```json
+   {
      "name": "<namespace>/composer-test",
      "type": "library",
      "license": "GPL-3.0-only",
      "version": "1.0.0"
-}
-```
+   }
+   ```
+
+1. Run Git commands to tag the changes and push them to your repository:
 
-Replace `<namespace>` with a unique namespace like your GitLab username or group name.
+   ```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
+   ```
 
-After this basic package structure is created, we need to tag it in Git and push it to the repository.
+The package is now in your GitLab Package Registry.
 
-```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
-```
+## Publish a Composer package by using the API
 
-### Publishing the package
+Publish a Composer package to the Package Registry,
+so that anyone who can access the project can use the package as a dependency.
 
-Now that the basics of our project is completed, we can publish the package.
-To publish the package, you need:
+Prerequisites:
 
-- A personal access token or `CI_JOB_TOKEN`.
+- A package 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`.
 
-  ([Deploy tokens](./../../project/deploy_tokens/index.md) are not yet supported for use with Composer.)
+  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.
 
-- Your project ID which can be found on the home page of your project.
+To publish the package:
 
-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:
+- Send a `POST` request to the [Packages API](../../../api/packages.md).
  
-You can generate a [personal access token](../../../user/profile/personal_access_tokens.md) with the scope set to `api` for repository authentication. For example:
+  For example, you can use `curl`:
 
-```shell
-curl --data tag=<tag> 'https://__token__:<personal-access-token>@gitlab.com/api/v4/projects/<project_id>/packages/composer'
-```
+  ```shell
+  curl --data tag=<tag> "https://__token__:<personal-access-token>@gitlab.example.com/api/v4/projects/<project_id>/packages/composer"
+  ```
 
-Where:
+  - `<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>`.
 
-- `<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.
+You can view the published package by going to **Packages & Registries > Package Registry** and
+selecting the **Composer** tab.
 
-If the above command succeeds, you now should be able to see the package under the **Packages & Registries** section of your project page.
+## Publish a Composer package by using CI/CD
 
-### Publishing the package with CI/CD
+You can publish a Composer package to the Package Registry as part of your CI/CD process.
 
-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:
+1. Specify a `CI_JOB_TOKEN` in your `.gitlab-ci.yml` file:
 
-```yaml
-stages:
+   ```yaml
+   stages:
      - deploy
 
-deploy:
+   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. Run the pipeline.
+
+You can view the published package by going to **Packages & Registries > Package Registry** and selecting the **Composer** tab.
+
+### Use a CI/CD template
 
-### Installing a package
+A more detailed Composer CI/CD file is also available as a `.gitlab-ci.yml` template:
 
-To install your package, you need:
+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**.
 
-- 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.
+CAUTION: **Warning:**
+Do not save unless you want to overwrite the existing CI/CD file.
 
-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:
+## Install a Composer package
 
-```json
-{
+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`.
+
+  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.
+
+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:
+
+   ```json
+   {
      ...
      "repositories": [
-    { "type": "composer", "url": "https://gitlab.com/api/v4/group/<group_id>/-/packages/composer/packages.json" }
+       { "type": "composer", "url": "https://gitlab.example.com/api/v4/group/<group_id>/-/packages/composer/packages.json" }
      ],
      "require": {
        ...
        "<package_name>": "<version>"
      },
      ...
-}
-```
-
-Where:
-
-- `<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).
-
-You also need to create a `auth.json` file with your GitLab credentials:
-
-```json
-{
-    "gitlab-token": {
-       "gitlab.com": "<personal_access_token>"
    }
-}
-```
-
-Where:
+   ```
 
-- `<personal_access_token>` is your personal access token.
+   - `<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.
 
-With the `composer.json` and `auth.json` files configured, you can install the package by running `composer`:
+1. Create an `auth.json` file with your GitLab credentials:
 
-```shell
-composer update
-```
+   ```shell
+   composer config gitlab-token.<DOMAIN-NAME> <personal_access_token> 
+   ```
 
-If successful, you should be able to see the output indicating that the package has been successfully installed.
+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).

doc/user/packages/package_registry/index.md

@@ -31,7 +31,7 @@ authenticate with GitLab by using the `CI_JOB_TOKEN`.
 
 CI/CD templates, which you can use to get started, are in [this repo](https://gitlab.com/gitlab-org/gitlab/-/tree/master/lib/gitlab/ci/templates).
 
-Learn more about [using CI/CD to build Maven packages](../maven_repository/index.md#creating-maven-packages-with-gitlab-cicd), [NPM packages](../npm_registry/index.md#publishing-a-package-with-cicd), [Composer packages](../composer_repository/index.md#publishing-the-package-with-cicd), [NuGet Packages](../nuget_repository/index.md#publishing-a-nuget-package-with-cicd), [Conan Packages](../conan_repository/index.md#using-gitlab-ci-with-conan-packages), and [PyPI packages](../pypi_repository/index.md#using-gitlab-ci-with-pypi-packages).
+Learn more about [using CI/CD to build Maven packages](../maven_repository/index.md#creating-maven-packages-with-gitlab-cicd), [NPM packages](../npm_registry/index.md#publishing-a-package-with-cicd), [Composer packages](../composer_repository/index.md#publish-a-composer-package-by-using-cicd), [NuGet Packages](../nuget_repository/index.md#publishing-a-nuget-package-with-cicd), [Conan Packages](../conan_repository/index.md#using-gitlab-ci-with-conan-packages), and [PyPI packages](../pypi_repository/index.md#using-gitlab-ci-with-pypi-packages).
 
 If you use CI/CD to build a package, extended activity
 information is displayed when you view the package details: