diff options
Diffstat (limited to 'doc/user/packages/composer_repository/index.md')
-rw-r--r-- | doc/user/packages/composer_repository/index.md | 155 |
1 files changed, 155 insertions, 0 deletions
diff --git a/doc/user/packages/composer_repository/index.md b/doc/user/packages/composer_repository/index.md new file mode 100644 index 00000000000..8a7c70ec74d --- /dev/null +++ b/doc/user/packages/composer_repository/index.md @@ -0,0 +1,155 @@ +--- +stage: Package +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 **(PREMIUM)** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/15886) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.1. + +With the GitLab Composer Repository, every project can have its own space to store [Composer](https://getcomposer.org/) packages. + +## Enabling the Composer Repository + +NOTE: **Note:** +This option is available only if your GitLab administrator has +[enabled support for the Package Registry](../../../administration/packages/index.md). **(PREMIUM ONLY)** + +After the Composer Repository is enabled, it will be available for all new projects +by default. To enable it for existing projects, or if you want to disable it: + +1. Navigate to your project's **Settings > General > Permissions**. +1. Find the Packages feature and enable or disable it. +1. Click on **Save changes** for the changes to take effect. + +You should then be able to see the **Packages & Registries** section on the left sidebar. + +## Getting started + +This section will cover creating a new example Composer package to publish. This is a +quickstart to test out the **GitLab Composer Registry**. + +You will 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 +{ + "name": "<namespace>/composer-test", + "type": "library", + "license": "GPL-3.0-only", + "version": "1.0.0" +} +``` + +Replace `<namespace>` with a unique namespace like your GitLab username or group name. + +After this basic package structure is created, we need to tag it in Git and push it to the repository. + +```shell +git init +git add composer.json +git commit -m 'Composer package test' +git tag v1.0.0 +git add origin git@gitlab.com:<namespace>/<project-name>.git +git push origin v1.0.0 +``` + +### Publishing the package + +Now that the basics of our project is completed, we can publish the package. +For accomplishing this you will need the following: + +- 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 project ID which can be found on the home page of your project. + +To publish the package hosted on GitLab we'll need to make a `POST` to the GitLab package API using a tool like `curl`: + +```shell +curl --data tag=<tag> 'https://__token__:<personal-access-token>@gitlab.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. In this example it should be `v1.0.0`. Notice that instead of `tag=<tag>` you can also use `branch=<branch>` to publish branches. + +If the above command succeeds, you now should be able to see the package under the **Packages & Registries** section of your project page. + +### Installing a package + +To install your package you will need: + +- 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. + +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: + +```json +{ + ... + "repositories": [ + { "type": "composer", "url": "https://gitlab.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 will also need to create a `auth.json` file with your GitLab credentials: + +```json +{ + "http-basic": { + "gitlab.com": { + "username": "___token___", + "password": "<personal_access_token>" + } + } +} +``` + +Where: + +- `<personal_access_token>` is your personal access token. + +With the `composer.json` and `auth.json` files configured, you can install the package by running `composer`: + +```shell +composer update +``` + +If successful, you should be able to see the output indicating 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, +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/examples/authenticating-with-hashicorp-vault/index.md). |