doc/user/packages/composer_repository/_index.md
{{< details >}}
{{< /details >}}
[!warning] The Composer package registry for GitLab is under development and isn't ready for production use due to limited functionality. This epic details the remaining work and timelines to make it production ready.
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 to the package registry, so that anyone who can access the project can use the package as a dependency.
Prerequisites:
1.0.0.0), an
error (Validation failed: Version is invalid) occurs when you publish.composer.json file at the project root directory.api.write_package_registry.To publish the package with a personal access token:
Send a POST request to the Packages API.
For example, you can use curl:
curl --fail-with-body --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, use branch=<branch> instead of tag=<tag>.To publish the package with a deploy token:
Send a POST request to the Packages API.
For example, you can use curl:
curl --fail-with-body --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, use branch=<branch> instead of tag=<tag>.You can view the published package by going to Deploy > Package registry and selecting the Composer tab.
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 --fail-with-body --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.
A more detailed Composer CI/CD file is also available as a .gitlab-ci.yml template:
[!warning] Do not save unless you want to overwrite the existing CI/CD file.
When you publish:
400 Bad request error occurs.Install a package from the package registry so you can use it as a dependency.
Prerequisites:
api.read_package_registry, write_package_registry, or both.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's composer.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 URL gitlab.com or gitlab.example.com.<personal_access_token> with the scope set to api, or <deploy_token> with the scope set
to read_package_registry and/or write_package_registry.If you are on GitLab Self-Managed, add gitlab-domains to composer.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
[!note] On GitLab.com, Composer uses the GitLab token from
auth.jsonas a private token by default. Without thegitlab-domainsdefinition 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 and auth.json files configured, you can install the package by running:
composer update
Or to install the single package:
composer req <package-name>:<package-version>
[!warning] Never commit the
auth.jsonfile to your repository. To install packages from a CI/CD job, consider using thecomposer configtool with your access token stored in a GitLab CI/CD variable or in HashiCorp Vault.
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 the preferred-install field under the config key:
{
...
"config": {
"preferred-install": {
"<package name>": "source"
}
}
...
}
{{< history >}}
composer_use_ssh_source_urls. Disabled by default.composer_use_ssh_source_urls removed.{{< /history >}}
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:
https Git URL is used. Make sure you can clone the repository with HTTPS.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.
Although Composer packages are accessed at the group level, a group or project deploy token can be used to access them:
Prerequisites:
Before you delete a package, make sure you understand the associated security risks.
To delete a package, you can either:
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
composer installAuthorization 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.
The file composer.json was not foundYou 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.
The GitLab Composer repository supports the following Composer CLI commands:
composer install: Install Composer dependencies.composer update: Install the latest version of Composer dependencies.