1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
|
---
stage: Package
group: Package Registry
info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments
---
# Composer packages in the Package Registry **(FREE)**
> - [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.
> - Deploy token support [added](https://gitlab.com/gitlab-org/gitlab/-/issues/240897) in GitLab 14.6.
WARNING:
The Composer package registry for GitLab is under development and isn't ready for production use due to
limited functionality. This [epic](https://gitlab.com/groups/gitlab-org/-/epics/6817) details the remaining
work and timelines to make it production ready.
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.
For documentation of the specific API endpoints that the Composer
client uses, see the [Composer API documentation](../../../api/packages/composer.md).
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](../workflows/build_packages.md#composer).
## 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](https://getcomposer.org/doc/04-schema.md#version).
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.
- 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](../../../user/profile/personal_access_tokens.md) with the scope set to `api`.
- A [deploy token](../../project/deploy_tokens/index.md)
with the scope set to `write_package_registry`.
To publish the package with a personal access token:
- Send a `POST` request to the [Packages API](../../../api/packages.md).
For example, you can use `curl`:
```shell
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, use `branch=<branch>` instead of `tag=<tag>`.
To publish the package with a deploy token:
- Send a `POST` request to the [Packages API](../../../api/packages.md).
For example, you can use `curl`:
```shell
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, use `branch=<branch>` instead of `tag=<tag>`.
You can view the published package by going to **Packages and registries > 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.
1. Specify a `CI_JOB_TOKEN` in your `.gitlab-ci.yml` file:
```yaml
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
```
1. Run the pipeline.
To view the published package, go to **Packages and registries > 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:
1. On the left sidebar, select **Project information**.
1. Above the file list, select **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**.
WARNING:
Do not save unless you want to overwrite the existing CI/CD file.
## 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](../../../api/packages/composer.md#download-a-package-archive) was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/331601) 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](../../../user/profile/personal_access_tokens.md)
with the scope set to, at minimum, `api`.
- A [deploy token](../../project/deploy_tokens/index.md)
with the scope set to `read_package_registry`, `write_package_registry`, or both.
To install a package:
1. 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:
```shell
composer config repositories.<group_id> composer https://gitlab.example.com/api/v4/group/<group_id>/-/packages/composer/
```
- Set the required package version:
```shell
composer require <package_name>:<version>
```
Result in the `composer.json` file:
```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:
Using a personal access token:
```shell
composer config gitlab-token.<DOMAIN-NAME> <personal_access_token>
```
Result in the `auth.json` file:
```json
{
...
"gitlab-token": {
"<DOMAIN-NAME>": "<personal_access_token>",
...
}
}
```
Using a deploy token:
```shell
composer config gitlab-token.<DOMAIN-NAME> <deploy_token_username> <deploy_token>
```
Result in the `auth.json` file:
```json
{
...
"gitlab-token": {
"<DOMAIN-NAME>": {
"username": "<deploy_token_username>",
"token": "<deploy_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 `api`, or `<deploy_token>` with the scope set
to `read_package_registry` and/or `write_package_registry`.
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:
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.
1. With the `composer.json` and `auth.json` files configured, you can install the package by running:
```shell
composer update
```
Or to install the single package:
```shell
composer req <package-name>:<package-version>
```
If successful, you should see output indicating that the package installed successfully.
You can also install from source (by pulling the Git repository directly) using the
`--prefer-source` option:
```shell
composer update --prefer-source
```
WARNING:
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.md#satis) tool with your access token
stored in a [GitLab CI/CD variable](../../../ci/variables/index.md) or in
[HashiCorp Vault](../../../ci/secrets/index.md).
### 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. Note that 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:
```shell
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](../../../api/packages/composer.md#download-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](#install-a-composer-package) section to create an `auth.json` file.
## 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.
|