GitLab Composer Repository (PREMIUM)

Introduced in GitLab Premium 13.1.

With the GitLab Composer Repository, every project can have its own space to store Composer packages.

Enabling the Composer Repository

NOTE: Note: This option is available only if your GitLab administrator has enabled support for the Package Registry. (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.
2. Find the Packages feature and enable or disable it.
3. 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.

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:

mkdir my-composer-package && cd my-composer-package

Create a new composer.json file inside this directory to set up the basic project:

touch composer.json

Inside composer.json, add the following code:

{
  "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.

git init
git add composer.json
git commit -m 'Composer package test'
git tag v1.0.0
git add origin [email protected]:<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 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:

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 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:

{
  ...
  "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:

{
    "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:

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 tool with your personal access token stored in a GitLab CI/CD environment variable or in Hashicorp Vault.