Composer packages in the package registry All tiers All offerings Beta
- Introduced in GitLab 13.2.
- Moved from GitLab Premium to GitLab Free in 13.3.
- Support for Composer 2.0 added in GitLab 13.10.
- Deploy token support added in GitLab 14.6.
Publish Composer packages in your project’s package registry. Then, install the packages whenever you need to use them as a dependency.
For documentation of the specific API endpoints that the Composer client uses, see the Composer API documentation.
Composer v2.0 is recommended. Composer v1.0 is supported, but it has lower performance when working in groups with very large numbers of packages.
Learn how to build a Composer package.
Publish a Composer package by using the API
Publish a Composer package to the package registry, so that anyone who can access the project can use the package as a dependency.
Prerequisites:
- A package in a GitLab repository. Composer packages should be versioned based on
the Composer specification.
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. - A valid
composer.json
file at the project root directory. - The Packages feature is enabled in a GitLab repository.
- The project ID, which is on the project’s home page.
- One of the following token types:
- A personal access token with the scope set to
api
. - A deploy token
with the scope set to
write_package_registry
.
- A personal access token with the scope set to
To publish the package with a personal access token:
-
Send a
POST
request to the Packages API.For example, you can use
curl
:curl --data tag=<tag> "https://__token__:<personal-access-token>@gitlab.example.com/api/v4/projects/<project_id>/packages/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, usebranch=<branch>
instead oftag=<tag>
.
-
To publish the package with a deploy token:
-
Send a
POST
request to the Packages API.For example, you can use
curl
:curl --data tag=<tag> --header "Deploy-Token: <deploy-token>" "https://gitlab.example.com/api/v4/projects/<project_id>/packages/composer"
-
<deploy-token>
is your deploy token -
<project_id>
is your project ID. -
<tag>
is the Git tag name of the version you want to publish. To publish a branch, usebranch=<branch>
instead oftag=<tag>
.
-
You can view the published package by going to Deploy > Package Registry and selecting the Composer tab.
Publish a Composer package by using CI/CD
You can publish a Composer package to the package registry as part of your CI/CD process.
-
Specify a
CI_JOB_TOKEN
in your.gitlab-ci.yml
file:stages: - deploy deploy: stage: deploy script: - apk add curl - 'curl --header "Job-Token: $CI_JOB_TOKEN" --data tag=<tag> "${CI_API_V4_URL}/projects/$CI_PROJECT_ID/packages/composer"' environment: production
-
Run the pipeline.
To view the published package, go to Deploy > Package Registry and select the Composer tab.
Use a CI/CD template
A more detailed Composer CI/CD file is also available as a .gitlab-ci.yml
template:
- On the left sidebar, select Project overview.
- Above the file list, select Set up CI/CD. If this button is not available, select CI/CD Configuration and then Edit.
- From the Apply a template list, select Composer.
Publishing packages with the same name or version
When you publish:
- The same package with different data, it overwrites the existing package.
- The same package with the same data, a
400 Bad request
error occurs.
Install a Composer package
Authorization to download a package archive was introduced in GitLab 14.10.
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.
- One of the following token types:
- A personal access token
with the scope set to, at minimum,
api
. - A deploy token
with the scope set to
read_package_registry
,write_package_registry
, or both. - A CI/CD Job token
- A personal access token
with the scope set to, at minimum,
To install a package:
-
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:
composer config repositories.<group_id> composer https://gitlab.example.com/api/v4/group/<group_id>/-/packages/composer/packages.json
- Set the required package version:
composer require <package_name>:<version>
Result in the
composer.json
file:{ ... "repositories": { "<group_id>": { "type": "composer", "url": "https://gitlab.example.com/api/v4/group/<group_id>/-/packages/composer/packages.json" }, ... }, "require": { ... "<package_name>": "<version>" }, ... }
You can unset this with the command:
composer config --unset repositories.<group_id>
-
<group_id>
is the group ID. -
<package_name>
is the package name defined in your package’scomposer.json
file. -
<version>
is the package version.
-
Create an
auth.json
file with your GitLab credentials:Using a personal access token:
composer config gitlab-token.<DOMAIN-NAME> <personal_access_token>
Result in the
auth.json
file:{ ... "gitlab-token": { "<DOMAIN-NAME>": "<personal_access_token>", ... } }
Using a deploy token:
composer config gitlab-token.<DOMAIN-NAME> <deploy_token_username> <deploy_token>
Result in the
auth.json
file:{ ... "gitlab-token": { "<DOMAIN-NAME>": { "username": "<deploy_token_username>", "token": "<deploy_token>", ... } }
Using a CI/CD job token:
composer config -- gitlab-token.<DOMAIN-NAME> gitlab-ci-token "${CI_JOB_TOKEN}"
Result in the
auth.json
file:{ ... "gitlab-token": { "<DOMAIN-NAME>": { "username": "gitlab-ci-token", "token": "<ci-job-token>", ... } }
You can unset this with the command:
composer config --unset --auth gitlab-token.<DOMAIN-NAME>
-
<DOMAIN-NAME>
is the GitLab instance URLgitlab.com
orgitlab.example.com
. -
<personal_access_token>
with the scope set toapi
, or<deploy_token>
with the scope set toread_package_registry
and/orwrite_package_registry
.
-
-
If you are on a GitLab self-managed instance, add
gitlab-domains
tocomposer.json
.composer config gitlab-domains gitlab01.example.com gitlab02.example.com
Result in the
composer.json
file:{ ... "repositories": [ { "type": "composer", "url": "https://gitlab.example.com/api/v4/group/<group_id>/-/packages/composer/packages.json" } ], "config": { ... "gitlab-domains": ["gitlab01.example.com", "gitlab02.example.com"] }, "require": { ... "<package_name>": "<version>" }, ... }
You can unset this with the command:
composer config --unset gitlab-domains
On GitLab.com, Composer uses the GitLab token fromauth.json
as a private token by default. Without thegitlab-domains
definition incomposer.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. -
With the
composer.json
andauth.json
files configured, you can install the package by running:composer update
Or to install the single package:
composer req <package-name>:<package-version>
auth.json
file to your repository. To install packages from a CI/CD job,
consider using the composer config
tool with your access token
stored in a GitLab CI/CD variable or in
HashiCorp Vault.Install from source
You can install from source by pulling the Git repository directly. To do so, either:
-
Use the
--prefer-source
option:composer update --prefer-source
-
In the
composer.json
, use thepreferred-install
field under theconfig
key:{ ... "config": { "preferred-install": { "<package name>": "source" } } ... }
SSH access
-
Introduced in GitLab 16.4 with a flag named
composer_use_ssh_source_urls
. Disabled by default. - Enabled on self-managed GitLab 16.5.
composer_use_ssh_source_urls
.
On GitLab.com, this feature is available.When you install from source, the composer
configures an
access to the project’s Git repository.
Depending on the project visibility, the access type is different:
- On public projects, the
https
Git URL is used. Make sure you can clone the repository with HTTPS. - On internal or private projects, the
ssh
Git URL is used. Make sure you can clone the repository with SSH.
You can access the ssh
Git URL from a CI/CD job using SSH keys with GitLab CI/CD.
Working with Deploy Tokens
Although Composer packages are accessed at the group level, a group or project deploy token can be used to access them:
- A group deploy token has access to all packages published to projects in that group or its subgroups.
- A project deploy token only has access to packages published to that particular project.
Troubleshooting
Caching
To improve performance, Composer caches files related to a package. Composer doesn’t remove data by itself. The cache grows as new packages are installed. If you encounter issues, clear the cache with this command:
composer clearcache
Authorization requirement when using composer install
In GitLab 14.9 and earlier, you did not require authorization to use composer install
if you already had a generated composer.lock
.
If you committed your composer.lock
, you could do a composer install
in CI without setting up credentials.
In GitLab 14.10 and later, authorization is required for the downloading a package archive endpoint.
If you encounter a credentials prompt when you are using composer install
, follow the instructions in the install a composer package section to create an auth.json
file.
Publish fails with The file composer.json was not found
You might see an error that says The file composer.json was not found
.
This issue occurs when configuration requirements for publishing a package are not met.
To resolve the error, commit a composer.json
file to the project root directory.
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.