Help us learn about your current experience with the documentation. Take the survey.

Composer packages in the package registry

Tier: 免费版、高级版、旗舰版
Offering: GitLab.com、GitLab 自托管、GitLab 专用版
Status: Beta

GitLab 的 Composer 包注册表正在开发中，由于功能有限，尚不适合生产环境使用。此 epic 详细说明了剩余的工作和时间表，以使其达到生产就绪状态。

在项目的包注册表中发布 Composer 包。然后，在需要将它们用作依赖项时安装这些包。

有关 Composer 客户端使用的特定 API 端点的文档，请参阅 Composer API 文档。

推荐使用 Composer v2.0。支持 Composer v1.0，但在处理包含大量包的组时性能较低。

学习如何构建 Composer 包。

使用 API 发布 Composer 包

将 Composer 包发布到包注册表，以便任何可以访问项目的人员都可以将该包用作依赖项。

先决条件：

GitLab 仓库中的包。Composer 包应根据 Composer 规范进行版本控制。如果版本无效，例如有三个点（1.0.0.0），发布时会出现错误（Validation failed: Version is invalid）。
项目根目录下的有效 composer.json 文件。
GitLab 仓库中已启用 Packages 功能。
项目 ID，显示在项目概览页面上。
以下令牌类型之一：
- 个人访问令牌，范围设置为 api。
- 部署令牌，范围设置为 write_package_registry。

使用个人访问令牌发布包：

向 Packages API 发送 POST 请求。

例如，您可以使用 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> 是您的个人访问令牌。
- <project_id> 是您的项目 ID。
- <tag> 是您要发布的版本的 Git 标签名称。要发布分支，请使用 branch=<branch> 而不是 tag=<tag>。

使用部署令牌发布包：

向 Packages API 发送 POST 请求。

例如，您可以使用 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> 是您的部署令牌
- <project_id> 是您的项目 ID。
- <tag> 是您要发布的版本的 Git 标签名称。要发布分支，请使用 branch=<branch> 而不是 tag=<tag>。

您可以通过转到 部署 > 包注册表 并选择 Composer 选项卡来查看已发布的包。

使用 CI/CD 发布 Composer 包

您可以将 Composer 包作为 CI/CD 流程的一部分发布到包注册表。

在您的 .gitlab-ci.yml 文件中指定 CI_JOB_TOKEN：

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

运行流水线。

要查看已发布的包，请转到 部署 > 包注册表 并选择 Composer 选项卡。

使用 CI/CD 模板

更详细的 Composer CI/CD 文件也可作为 .gitlab-ci.yml 模板使用：

在左侧边栏，选择 项目概览。
在文件列表上方，选择 设置 CI/CD。如果此按钮不可用，请选择 CI/CD 配置，然后选择编辑。
从 应用模板 列表中选择 Composer。

除非您想覆盖现有的 CI/CD 文件，否则不要保存。

发布同名或同版本的包

发布时：

不同数据的相同包，会覆盖现有包。
相同数据的相同包，会出现 400 Bad request 错误。

安装 Composer 包

从包注册表安装包，以便您可以将其用作依赖项。

先决条件：

包注册表中的包。
发布包的项目中已启用包注册表。
组 ID，位于组的首页上。
以下令牌类型之一：
- 个人访问令牌，范围至少设置为 api。
- 部署令牌，范围设置为 read_package_registry、write_package_registry 或两者。
- CI/CD 作业令牌

要安装包：

将包注册表 URL 添加到您项目的 composer.json 文件中，以及您要安装的包名称和版本：

连接到您组的包注册表：

composer config repositories.<group_id> composer https://gitlab.example.com/api/v4/group/<group_id>/-/packages/composer/packages.json

设置所需的包版本：

composer require <package_name>:<version>

composer.json 文件中的结果：

{
  ...
  "repositories": {
    "<group_id>": {
      "type": "composer",
      "url": "https://gitlab.example.com/api/v4/group/<group_id>/-/packages/composer/packages.json"
    },
    ...
  },
  "require": {
    ...
    "<package_name>": "<version>"
  },
  ...
}

您可以使用以下命令取消设置：

composer config --unset repositories.<group_id>

<group_id> 是组 ID。
<package_name> 是您的包的 composer.json 文件中定义的包名称。
<version> 是包版本。

使用您的 GitLab 凭据创建 auth.json 文件：

使用个人访问令牌：

composer config gitlab-token.<DOMAIN-NAME> <personal_access_token>

auth.json 文件中的结果：

{
  ...
  "gitlab-token": {
    "<DOMAIN-NAME>": "<personal_access_token>",
    ...
  }
}

使用部署令牌：

composer config gitlab-token.<DOMAIN-NAME> <deploy_token_username> <deploy_token>

auth.json 文件中的结果：

{
  ...
  "gitlab-token": {
    "<DOMAIN-NAME>": {
      "username": "<deploy_token_username>",
      "token": "<deploy_token>",
    ...
  }
}

使用 CI/CD 作业令牌：

composer config -- gitlab-token.<DOMAIN-NAME> gitlab-ci-token "${CI_JOB_TOKEN}"

auth.json 文件中的结果：

{
  ...
  "gitlab-token": {
    "<DOMAIN-NAME>": {
      "username": "gitlab-ci-token",
      "token": "<ci-job-token>",
    ...
  }
}

您可以使用以下命令取消设置：

composer config --unset --auth gitlab-token.<DOMAIN-NAME>

<DOMAIN-NAME> 是 GitLab 实例 URL gitlab.com 或 gitlab.example.com。
<personal_access_token> 范围设置为 api，或 <deploy_token> 范围设置为 read_package_registry 和/或 write_package_registry。

如果您使用的是 GitLab 自托管，请将 gitlab-domains 添加到 composer.json。

composer config gitlab-domains gitlab01.example.com gitlab02.example.com

composer.json 文件中的结果：

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

您可以使用以下命令取消设置：

composer config --unset gitlab-domains

在 GitLab.com 上，Composer 默认使用 auth.json 中的 GitLab 令牌作为私有令牌。如果 composer.json 中没有 gitlab-domains 定义，Composer 会将 GitLab 令牌用作基本认证，令牌作为用户名，空白密码。这会导致 401 错误。

配置好 composer.json 和 auth.json 文件后，您可以通过运行以下命令安装包：
```
composer update
```
或者安装单个包：
```
composer req <package-name>:<package-version>
```

切勿将 auth.json 文件提交到您的仓库。要从 CI/CD 作业安装包，请考虑使用 composer config 工具，并将您的访问令牌存储在 GitLab CI/CD 变量中或 HashiCorp Vault 中。

从源代码安装

您可以通过直接拉取 Git 仓库从源代码安装。为此，可以：

使用 --prefer-source 选项：
```
composer update --prefer-source
```

在 composer.json 中，使用 config 键下的 preferred-install 字段：

{
  ...
  "config": {
    "preferred-install": {
      "<package name>": "source"
    }
  }
  ...
 }

SSH 访问

从源代码安装时，composer 配置对项目 Git 仓库的访问。根据项目可见性，访问类型不同：

在公共项目中，使用 https Git URL。确保您可以使用 HTTPS 克隆仓库。
在内部或私有项目中，使用 ssh Git URL。确保您可以使用 SSH 克隆仓库。

您可以使用 SSH 密钥与 GitLab CI/CD 从 CI/CD 作业访问 ssh Git URL。

使用部署令牌

尽管 Composer 包在组级别访问，但组或项目部署令牌可用于访问它们：

组部署令牌有权访问发布到该组或其子组中项目的所有包。
项目部署令牌仅有权访问发布到该特定项目的包。

故障排除

缓存

为了提高性能，Composer 缓存与包相关的文件。Composer 不会自行删除数据。随着新包的安装，缓存会增长。如果遇到问题，请使用以下命令清除缓存：

composer clearcache

使用 `composer install` 时的授权要求

下载包存档端点需要授权。如果您在使用 composer install 时遇到凭据提示，请按照安装 Composer 包部分的说明创建 auth.json 文件。

发布失败并显示 `The file composer.json was not found`

您可能会看到一条错误消息，显示 The file composer.json was not found。

当未满足发布包的配置要求时，会出现此问题。

要解决此错误，请将 composer.json 文件提交到项目根目录。

支持的 CLI 命令

GitLab Composer 存储库支持以下 Composer CLI 命令：

composer install：安装 Composer 依赖项。
composer update：安装最新版本的 Composer 依赖项。

Composer packages in the package registry

使用 API 发布 Composer 包

使用 CI/CD 发布 Composer 包

使用 CI/CD 模板

发布同名或同版本的包

安装 Composer 包

从源代码安装

SSH 访问

使用部署令牌

故障排除

缓存

使用 composer install 时的授权要求

发布失败并显示 The file composer.json was not found

支持的 CLI 命令

使用 `composer install` 时的授权要求

发布失败并显示 `The file composer.json was not found`