diff options
Diffstat (limited to 'doc/user/packages/composer_repository/index.md')
-rw-r--r-- | doc/user/packages/composer_repository/index.md | 315 |
1 files changed, 201 insertions, 114 deletions
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). |