2020-06-16 23:08:38 -04:00
---
stage: Package
group: Package
2020-11-26 01:09:20 -05:00
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/#assignments
2020-06-16 23:08:38 -04:00
---
2021-02-16 13:09:24 -05:00
# Composer packages in the Package Registry **(FREE)**
2020-05-29 14:08:26 -04:00
2021-11-17 16:13:37 -05:00
> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/15886) in GitLab 13.2.
> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/221259) from GitLab Premium to GitLab Free in 13.3.
> - Support for Composer 2.0 [added](https://gitlab.com/gitlab-org/gitlab/-/issues/259840) in GitLab 13.10.
2020-05-29 14:08:26 -04:00
2021-09-28 20:10:07 -04:00
WARNING:
The Composer package registry for GitLab is under development and isn't ready for production use due to
2021-10-13 14:12:40 -04:00
limited functionality. This [epic ](https://gitlab.com/groups/gitlab-org/-/epics/6817 ) details the remaining
work and timelines to make it production ready.
2021-09-28 20:10:07 -04:00
2020-09-28 08:10:02 -04:00
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.
2020-05-29 14:08:26 -04:00
2021-03-26 17:09:22 -04:00
For documentation of the specific API endpoints that the Composer
client uses, see the [Composer API documentation ](../../../api/packages/composer.md ).
2020-09-28 08:10:02 -04:00
## Create a Composer package
2020-05-29 14:08:26 -04:00
2020-09-28 08:10:02 -04:00
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.
2020-05-29 14:08:26 -04:00
2021-01-07 16:10:18 -05:00
WARNING:
If you are using a GitLab repository, the project must have been created from
a group's namespace, rather than a user's namespace. Composer packages
[can't be published to projects created from a user's namespace ](https://gitlab.com/gitlab-org/gitlab/-/issues/235467 ).
2020-09-28 08:10:02 -04:00
1. Create a directory called `my-composer-package` and change to that directory:
2020-05-29 14:08:26 -04:00
2020-09-28 08:10:02 -04:00
```shell
mkdir my-composer-package & & cd my-composer-package
```
2020-05-29 14:08:26 -04:00
2020-10-08 05:08:40 -04:00
1. Run [`composer init` ](https://getcomposer.org/doc/03-cli.md#init ) and answer the prompts.
2020-05-29 14:08:26 -04:00
2020-09-28 08:10:02 -04:00
For namespace, enter your unique [namespace ](../../../user/group/index.md#namespaces ), like your GitLab username or group name.
2020-05-29 14:08:26 -04:00
2020-09-28 08:10:02 -04:00
A file called `composer.json` is created:
2020-05-29 14:08:26 -04:00
2020-09-28 08:10:02 -04:00
```json
{
"name": "< namespace > /composer-test",
2020-10-12 14:08:31 -04:00
"description": "Library XY",
2020-09-28 08:10:02 -04:00
"type": "library",
"license": "GPL-3.0-only",
2020-10-12 14:08:31 -04:00
"authors": [
{
"name": "John Doe",
"email": "john@example.com"
}
],
"require": {}
2020-09-28 08:10:02 -04:00
}
```
2020-05-29 14:08:26 -04:00
2020-09-28 08:10:02 -04:00
1. Run Git commands to tag the changes and push them to your repository:
2020-05-29 14:08:26 -04:00
2020-09-28 08:10:02 -04:00
```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
2021-07-20 14:08:46 -04:00
git push --set-upstream origin main
2020-09-28 08:10:02 -04:00
git push origin v1.0.0
```
2020-05-29 14:08:26 -04:00
2020-09-28 08:10:02 -04:00
The package is now in your GitLab Package Registry.
2020-05-29 14:08:26 -04:00
2020-09-28 08:10:02 -04:00
## Publish a Composer package by using the API
2020-05-29 14:08:26 -04:00
2020-09-28 08:10:02 -04:00
Publish a Composer package to the Package Registry,
so that anyone who can access the project can use the package as a dependency.
2020-05-29 14:08:26 -04:00
2020-09-28 08:10:02 -04:00
Prerequisites:
2020-05-29 14:08:26 -04:00
2020-12-03 19:09:55 -05:00
- A package in a GitLab repository. Composer packages should be versioned based on
the [Composer specification ](https://getcomposer.org/doc/04-schema.md#version ).
2021-01-11 19:10:42 -05:00
If the version is not valid, for example, it has three dots (`1.0.0.0`), an
error (`Validation failed: Version is invalid`) occurs when you publish.
2020-10-12 14:08:31 -04:00
- A valid `composer.json` file.
- The Packages feature is enabled in a GitLab repository.
2020-09-28 08:10:02 -04:00
- 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` .
2020-05-29 14:08:26 -04:00
2020-12-04 16:09:29 -05:00
NOTE:
2020-11-08 22:09:03 -05:00
[Deploy tokens ](../../project/deploy_tokens/index.md ) are
2020-09-28 08:10:02 -04:00
[not yet supported ](https://gitlab.com/gitlab-org/gitlab/-/issues/240897 ) for use with Composer.
2020-05-29 14:08:26 -04:00
2020-09-28 08:10:02 -04:00
To publish the package:
2020-05-29 14:08:26 -04:00
2020-09-28 08:10:02 -04:00
- Send a `POST` request to the [Packages API ](../../../api/packages.md ).
2020-10-08 05:08:40 -04:00
2020-09-28 08:10:02 -04:00
For example, you can use `curl` :
2020-05-29 14:08:26 -04:00
2020-09-28 08:10:02 -04:00
```shell
curl --data tag=< tag > "https://__token__:< personal-access-token > @gitlab.example.com/api/v4/projects/< project_id > /packages/composer"
```
2020-05-29 14:08:26 -04:00
2020-09-28 08:10:02 -04:00
- `<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>` .
2020-05-29 14:08:26 -04:00
2020-09-28 08:10:02 -04:00
You can view the published package by going to **Packages & Registries > Package Registry** and
selecting the **Composer** tab.
2020-08-31 05:10:44 -04:00
2020-09-28 08:10:02 -04:00
## Publish a Composer package by using CI/CD
2020-08-31 05:10:44 -04:00
2020-09-28 08:10:02 -04:00
You can publish a Composer package to the Package Registry as part of your CI/CD process.
2020-05-29 14:08:26 -04:00
2020-09-28 08:10:02 -04:00
1. Specify a `CI_JOB_TOKEN` in your `.gitlab-ci.yml` file:
2020-05-29 14:08:26 -04:00
2020-09-28 08:10:02 -04:00
```yaml
stages:
- deploy
2020-09-01 20:10:29 -04:00
2020-09-28 08:10:02 -04:00
deploy:
stage: deploy
script:
2021-10-05 14:13:27 -04:00
- apk add curl
2021-05-24 14:10:28 -04:00
- 'curl --header "Job-Token: $CI_JOB_TOKEN" --data tag=< tag > "${CI_API_V4_URL}/projects/$CI_PROJECT_ID/packages/composer"'
2020-09-28 08:10:02 -04:00
```
2020-05-29 14:08:26 -04:00
2020-09-28 08:10:02 -04:00
1. Run the pipeline.
2020-05-29 14:08:26 -04:00
2020-12-01 13:09:42 -05:00
To view the published package, go to **Packages & Registries > Package Registry** and select the **Composer** tab.
2020-05-29 14:08:26 -04:00
2020-09-28 08:10:02 -04:00
### Use a CI/CD template
2020-05-29 14:08:26 -04:00
2020-09-28 08:10:02 -04:00
A more detailed Composer CI/CD file is also available as a `.gitlab-ci.yml` template:
2020-09-01 20:10:29 -04:00
2021-06-10 11:10:14 -04:00
1. On the left sidebar, select **Project information** .
2021-10-13 17:09:56 -04:00
1. Above the file list, select **Set up CI/CD** . If this button is not available, select **CI/CD Configuration** and then **Edit** .
2020-09-28 08:10:02 -04:00
1. From the **Apply a template** list, select **Composer** .
2020-09-01 20:10:29 -04:00
2020-12-04 16:09:29 -05:00
WARNING:
2020-09-28 08:10:02 -04:00
Do not save unless you want to overwrite the existing CI/CD file.
2020-09-01 20:10:29 -04:00
2020-12-17 04:10:19 -05:00
## Publishing packages with the same name or version
When you publish:
- The same package with different data, it overwrites the existing package.
2021-11-08 13:09:52 -05:00
- The same package with the same data, a `400 Bad request` error occurs.
2020-12-17 04:10:19 -05:00
2020-09-28 08:10:02 -04:00
## Install a Composer package
2020-09-01 20:10:29 -04:00
2020-09-28 08:10:02 -04:00
Install a package from the Package Registry so you can use it as a dependency.
2020-05-29 14:08:26 -04:00
2020-09-28 08:10:02 -04:00
Prerequisites:
2020-05-29 14:08:26 -04:00
2020-09-28 08:10:02 -04:00
- A package in the Package Registry.
2020-10-20 02:09:03 -04:00
- The group ID, which is on the group's home page.
2020-10-12 14:08:31 -04:00
- A [personal access token ](../../../user/profile/personal_access_tokens.md ) with the scope set to, at minimum, `read_api` .
2020-05-29 14:08:26 -04:00
2020-12-04 16:09:29 -05:00
NOTE:
2020-11-08 22:09:03 -05:00
[Deploy tokens ](../../project/deploy_tokens/index.md ) are
2020-09-28 08:10:02 -04:00
[not yet supported ](https://gitlab.com/gitlab-org/gitlab/-/issues/240897 ) for use with Composer.
2020-05-29 14:08:26 -04:00
2020-09-28 08:10:02 -04:00
To install a package:
2020-05-29 14:08:26 -04:00
2020-09-28 08:10:02 -04:00
1. Add the Package Registry URL to your project's `composer.json` file, along with the package name and version you want to install:
2020-05-29 14:08:26 -04:00
2020-10-12 14:08:31 -04:00
- 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:
2020-10-20 02:09:03 -04:00
```shell
2020-10-12 14:08:31 -04:00
composer require < package_name > :< version >
```
Result in the `composer.json` file:
2020-09-28 08:10:02 -04:00
```json
{
...
2020-10-12 14:08:31 -04:00
"repositories": {
"< group_id > ": {
"type": "composer",
"url": "https://gitlab.example.com/api/v4/group/< group_id > /-/packages/composer/"
},
...
},
2020-09-28 08:10:02 -04:00
"require": {
...
"< package_name > ": "< version > "
},
...
}
```
2020-05-29 14:08:26 -04:00
2020-10-12 14:08:31 -04:00
You can unset this with the command:
```shell
composer config --unset repositories.< group_id >
```
2020-09-28 08:10:02 -04:00
- `<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.
2020-05-29 14:08:26 -04:00
2020-09-28 08:10:02 -04:00
1. Create an `auth.json` file with your GitLab credentials:
2020-05-29 14:08:26 -04:00
2020-09-28 08:10:02 -04:00
```shell
2020-10-08 05:08:40 -04:00
composer config gitlab-token.< DOMAIN-NAME > < personal_access_token >
2020-09-28 08:10:02 -04:00
```
2020-05-29 14:08:26 -04:00
2020-10-12 14:08:31 -04:00
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:
2020-10-20 02:09:03 -04:00
2020-10-12 14:08:31 -04:00
```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 > "
},
...
}
2020-10-20 02:09:03 -04:00
```
2020-10-12 14:08:31 -04:00
You can unset this with the command:
```shell
composer config --unset gitlab-domains
```
2020-12-04 16:09:29 -05:00
NOTE:
2020-10-12 14:08:31 -04:00
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.
2021-03-16 17:11:53 -04:00
1. With the `composer.json` and `auth.json` files configured, you can install the package by running:
```shell
composer update
```
2021-03-18 14:09:09 -04:00
Or to install the single package:
```shell
composer req < package-name > :< package-version >
```
2021-03-16 17:11:53 -04:00
If successful, you should see output indicating that the package installed successfully.
2020-06-16 14:09:01 -04:00
2021-03-18 14:09:09 -04:00
You can also install from source (by pulling the Git repository directly) using the
`--prefer-source` option:
```shell
composer update --prefer-source
```
2020-12-04 16:09:29 -05:00
WARNING:
2020-09-28 08:10:02 -04:00
Never commit the `auth.json` file to your repository. To install packages from a CI/CD job,
2021-01-14 16:10:37 -05:00
consider using the [`composer config` ](https://getcomposer.org/doc/articles/handling-private-packages.md#satis ) tool with your personal access token
2021-06-28 11:08:03 -04:00
stored in a [GitLab CI/CD variable ](../../../ci/variables/index.md ) or in
2020-09-28 08:10:02 -04:00
[HashiCorp Vault ](../../../ci/secrets/index.md ).
2021-04-09 17:09:22 -04:00
## Supported CLI commands
The GitLab Composer repository supports the following Composer CLI commands:
- `composer install` : Install Composer dependencies.
- `composer update` : Install the latest version of Composer dependencies.