Skip to content

G
gitlab-ce
Commit 05c8483a authored by Suzanne Selhorn's avatar Suzanne Selhorn Committed by Achilleas Pipinellis
Browse files
Options

Docs: Revamp Composer topic 

Related to: https://gitlab.com/gitlab-org/gitlab/-/issues/247950
parent 02ab182c
Show whitespace changes
Inline Side-by-side
Showing with 111 additions and 118 deletions
doc/user/packages/composer_repository/index.md
View file @ 05c8483a
......@@ -4,172 +4,165 @@ 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
# Composer packages in the Package Registry
> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/15886) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.2.
> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/221259) to GitLab Core in 13.3.
With the GitLab Composer Repository, every project can have its own space to store [Composer](https://getcomposer.org/) packages.
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.
## Enabling the Composer Repository
## Create a Composer package
NOTE: **Note:**
This option is available only if your GitLab administrator has
[enabled support for the Package Registry](../../../administration/packages/index.md).
If you do not have a Composer package, create one and check it in to
a repository. This example shows a GitLab repository, but the repository
can be any public or private repository.
When the Composer Repository is enabled, it is available for all new projects
by default. To enable it for existing projects, or if you want to disable it:
1. Create a directory called `my-composer-package` and change to that directory:
1. Navigate to your project's **Settings > General > Visibility, project features, permissions**.
1. Find the Packages feature and enable or disable it.
1. Click on **Save changes** for the changes to take effect.
```shell
mkdir my-composer-package && cd my-composer-package
```
You should then be able to see the **Packages & Registries** section on the left sidebar.
1. Run [`composer init`](https://getcomposer.org/doc/03-cli.md#init) and answer the prompts.
## Getting started
For namespace, enter your unique [namespace](../../../user/group/index.md#namespaces), like your GitLab username or group name.
This section covers creating a new example Composer package to publish. This is a
quickstart to test out the **GitLab Composer Registry**.
A file called `composer.json` is created:
To complete this section, you 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
{
```json
{
"name": "<namespace>/composer-test",
"type": "library",
"license": "GPL-3.0-only",
"version": "1.0.0"
}
```
}
```
1. Run Git commands to tag the changes and push them to your repository:
Replace `<namespace>` with a unique namespace like your GitLab username or group name.
```shell
git init
git add composer.json
git commit -m 'Composer package test'
git tag v1.0.0
git remote add origin git@gitlab.example.com:<namespace>/<project-name>.git
git push --set-upstream origin master
git push origin v1.0.0
```
After this basic package structure is created, we need to tag it in Git and push it to the repository.
The package is now in your GitLab Package Registry.
```shell
git init
git add composer.json
git commit -m 'Composer package test'
git tag v1.0.0
git remote add origin git@gitlab.com:<namespace>/<project-name>.git
git push --set-upstream origin master
git push origin v1.0.0
```
## Publish a Composer package by using the API
### Publishing the package
Publish a Composer package to the Package Registry,
so that anyone who can access the project can use the package as a dependency.
Now that the basics of our project is completed, we can publish the package.
To publish the package, you need:
Prerequisites:
- A personal access token or `CI_JOB_TOKEN`.
- A package in a GitLab repository.
- The project ID, which is on the project's home page.
- A [personal access token](../../../user/profile/personal_access_tokens.md) with the scope set to `api`.
([Deploy tokens](./../../project/deploy_tokens/index.md) are not yet supported for use with Composer.)
NOTE: **Note:**
[Deploy tokens](./../../project/deploy_tokens/index.md) are
[not yet supported](https://gitlab.com/gitlab-org/gitlab/-/issues/240897) for use with Composer.
- Your project ID which can be found on the home page of your project.
To publish the package:
To publish the package hosted on GitLab, make a `POST` request to the GitLab package API.
A tool like `curl` can be used to make this request:
- Send a `POST` request to the [Packages API](../../../api/packages.md).
You can generate a [personal access token](../../../user/profile/personal_access_tokens.md) with the scope set to `api` for repository authentication. For example:
For example, you can use `curl`:
```shell
curl --data tag=<tag> 'https://__token__:<personal-access-token>@gitlab.com/api/v4/projects/<project_id>/packages/composer'
```
```shell
curl --data tag=<tag> "https://__token__:<personal-access-token>@gitlab.example.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.
To publish a branch, use `branch=<branch>` instead of `tag=<tag>`.
- `<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.
You can view the published package by going to **Packages & Registries > Package Registry** and
selecting the **Composer** tab.
If the above command succeeds, you now should be able to see the package under the **Packages & Registries** section of your project page.
## Publish a Composer package by using CI/CD
### Publishing the package with CI/CD
You can publish a Composer package to the Package Registry as part of your CI/CD process.
To work with Composer commands within [GitLab CI/CD](./../../../ci/README.md), you can
publish Composer packages by using `CI_JOB_TOKEN` in your `.gitlab-ci.yml` file:
1. Specify a `CI_JOB_TOKEN` in your `.gitlab-ci.yml` file:
```yaml
stages:
```yaml
stages:
- deploy
deploy:
deploy:
stage: deploy
script:
- 'curl --header "Job-Token: $CI_JOB_TOKEN" --data tag=<tag> "https://gitlab.example.com/api/v4/projects/$CI_PROJECT_ID/packages/composer"'
```
```
1. Run the pipeline.
You can view the published package by going to **Packages & Registries > Package Registry** and selecting the **Composer** tab.
### Use a CI/CD template
### Installing a package
A more detailed Composer CI/CD file is also available as a `.gitlab-ci.yml` template:
To install your package, you need:
1. On the left sidebar, click **Project overview**.
1. Above the file list, click **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**.
- 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.
CAUTION: **Warning:**
Do not save unless you want to overwrite the existing CI/CD file.
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:
## Install a Composer package
```json
{
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.
- A [personal access token](../../../user/profile/personal_access_tokens.md) with the scope set to `api`.
NOTE: **Note:**
[Deploy tokens](./../../project/deploy_tokens/index.md) are
[not yet supported](https://gitlab.com/gitlab-org/gitlab/-/issues/240897) for use with Composer.
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:
```json
{
...
"repositories": [
{ "type": "composer", "url": "https://gitlab.com/api/v4/group/<group_id>/-/packages/composer/packages.json" }
{ "type": "composer", "url": "https://gitlab.example.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 also need to create a `auth.json` file with your GitLab credentials:
```json
{
"gitlab-token": {
"gitlab.com": "<personal_access_token>"
}
}
```
Where:
```
- `<personal_access_token>` is your personal access token.
- `<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.
With the `composer.json` and `auth.json` files configured, you can install the package by running `composer`:
1. Create an `auth.json` file with your GitLab credentials:
```shell
composer update
```
```shell
composer config gitlab-token.<DOMAIN-NAME> <personal_access_token>
```
If successful, you should be able to see the output indicating that the package has been successfully installed.
Output indicates 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,
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-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/secrets/index.md).
[HashiCorp Vault](../../../ci/secrets/index.md).
doc/user/packages/package_registry/index.md
View file @ 05c8483a
......@@ -31,7 +31,7 @@ authenticate with GitLab by using the `CI_JOB_TOKEN`.
CI/CD templates, which you can use to get started, are in [this repo](https://gitlab.com/gitlab-org/gitlab/-/tree/master/lib/gitlab/ci/templates).
Learn more about [using CI/CD to build Maven packages](../maven_repository/index.md#creating-maven-packages-with-gitlab-cicd), [NPM packages](../npm_registry/index.md#publishing-a-package-with-cicd), [Composer packages](../composer_repository/index.md#publishing-the-package-with-cicd), [NuGet Packages](../nuget_repository/index.md#publishing-a-nuget-package-with-cicd), [Conan Packages](../conan_repository/index.md#using-gitlab-ci-with-conan-packages), and [PyPI packages](../pypi_repository/index.md#using-gitlab-ci-with-pypi-packages).
Learn more about [using CI/CD to build Maven packages](../maven_repository/index.md#creating-maven-packages-with-gitlab-cicd), [NPM packages](../npm_registry/index.md#publishing-a-package-with-cicd), [Composer packages](../composer_repository/index.md#publish-a-composer-package-by-using-cicd), [NuGet Packages](../nuget_repository/index.md#publishing-a-nuget-package-with-cicd), [Conan Packages](../conan_repository/index.md#using-gitlab-ci-with-conan-packages), and [PyPI packages](../pypi_repository/index.md#using-gitlab-ci-with-pypi-packages).
If you use CI/CD to build a package, extended activity
information is displayed when you view the package details:
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment
GitLab Nexedi Edition | About GitLab | About Nexedi | 沪ICP备2021021310号-2 | 沪ICP备2021021310号-7