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
|
---
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).
|
