パッケージレジストリ内のComposerパッケージ

プラン: Free、Premium、Ultimate
提供形態: GitLab.com、GitLab Self-Managed、GitLab Dedicated
ステータス: ベータ

GitLabのComposerパッケージレジストリは開発中であり、機能が限られているため、本番環境での使用には適していません。このエピックでは、本番環境で使用できるようになるまでの残りの作業とタイムラインについて詳しく説明します。

プロジェクトのパッケージレジストリにComposerパッケージを公開します。その後、依存関係として使用する必要があるときはいつでもパッケージをインストールします。

Composerクライアントが使用する特定のAPIエンドポイントのドキュメントについては、Composer APIドキュメントを参照してください。

Composer v2.0を推奨します。Composer v1.0もサポートされていますが、非常に多数のパッケージを含むグループで作業する場合、パフォーマンスが低下します。

Composerパッケージをビルドする方法をご覧ください。

APIを使用してComposerパッケージを公開する

プロジェクトにアクセスできるすべてのユーザーが依存関係としてパッケージを使用できるように、Composerパッケージをパッケージレジストリに公開します。

前提要件:

GitLabリポジトリ内のパッケージ。Composerパッケージは、Composer仕様に基づいてバージョニングする必要があります。バージョンが無効な場合（たとえば、3つのドット（1.0.0.0）がある場合）、公開時にエラー（Validation failed: Version is invalid）が発生します。
プロジェクトルートディレクトリにある有効なcomposer.jsonファイル。
GitLabリポジトリでパッケージ機能が有効になっている。
プロジェクトは、プロジェクトの概要ページに表示されます。
次のトークンタイプのうちの1つ:
- スコープがapiに設定されたパーソナルアクセストークン。
- write_package_registryにスコープが設定されたデプロイトークン。

パーソナルアクセストークンを使用してパッケージを公開するには:

パッケージ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>はプロジェクトです。
- <tag>は、公開するバージョンのGitリポジトリのタグ名です。ブランチを公開するには、tag=<tag>の代わりにbranch=<branch>を使用します。

デプロイトークンを使用してパッケージを公開するには:

パッケージ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>はプロジェクトです。
- <tag>は、公開するバージョンのGitリポジトリのタグ名です。ブランチを公開するには、tag=<tag>の代わりにbranch=<branch>を使用します。

デプロイ > パッケージレジストリに移動し、Composerタブを選択すると、公開されたパッケージを表示できます。

CI/CDを使用してComposerパッケージを公開する

CI/CDプロセスの一部として、Composerパッケージをパッケージレジストリに公開できます。

.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テンプレートとしても使用できます:

左側のサイドバーでProject overview（プロジェクトの概要）を選択します。
ファイルリストの上にあるCI/CDを設定を選択します。このボタンを使用できない場合は、CI/CD Configuration（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です。
スコープがapiに設定された<personal_access_token>、またはスコープがread_package_registryおよび/またはwrite_package_registryに設定された<deploy_token>。

GitLabセルフマネージドを使用している場合は、composer.jsonにgitlab-domainsを追加します。
```
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で、preferred-installフィールドをconfigキーの下で使用します:

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

SSHアクセス

ソースからインストールすると、composerはプロジェクトのGitリポジトリへのアクセスを設定します。プロジェクトの表示レベルに応じて、アクセスの種類が異なります:

パブリックプロジェクトでは、https Git URLが使用されます。HTTPSを使用してリポジトリをクローンできることを確認してください。
内部プロジェクトまたはプライベートプロジェクトでは、ssh Git URLが使用されます。SSHを使用してリポジトリをクローンできることを確認してください。

GitLab CI/CDでSSHキーを使用すると、CI/CDジョブからssh Git URLにアクセスできます。

デプロイトークンの操作

Composerパッケージはグループレベルでアクセスされますが、グループまたはプロジェクトのデプロイトークンを使用してアクセスできます:

グループデプロイトークンは、そのグループまたはサブグループのプロジェクトに公開されたすべてのパッケージにアクセスできます。
プロジェクトデプロイトークンは、その特定のプロジェクトに公開されたパッケージにのみアクセスできます。

トラブルシューティング

キャッシュ

パフォーマンスを向上させるため、Composerはパッケージに関連するファイルをキャッシュします。Composerはデータを自動的に削除しません。新しいパッケージがインストールされるにつれて、キャッシュは増加します。問題が発生した場合は、次のコマンドでキャッシュをクリアします:

composer clearcache

`composer install`を使用する場合の認可要件

パッケージアーカイブのダウンロードエンドポイントには、認可が必要です。composer installを使用しているときに認証情報のプロンプトが表示された場合は、パッケージのインストールセクションの手順に従って、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パッケージ

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`での公開が失敗する