GitLab Generic Packagesリポジトリ

リリースバイナリのような一般的なファイルをプロジェクトのパッケージレジストリに公開します。そして、依存関係として使用する必要があるときはいつでもパッケージをインストールしてください。

パッケージレジストリへの認証

パッケージレジストリを認証するには、個人アクセストークン、CI/CDジョブトークン、デプロイトークンのいずれかが必要です。

標準的なAPI認証メカニズムに加えて、汎用パッケージAPIは他の利用可能なメカニズムをサポートしないツールで使用するためにHTTP Basic認証による認証を許可します。user-id はチェックされず、どのような値でもかまいません。password は、個人アクセストークン、CI/CD ジョブトークン、デプロイトークンのいずれかでなければなりません。

ここで説明されている以外の認証方法は使用しないでください。文書化されていない認証方法は、将来削除される可能性があります。

パッケージファイルの公開

パッケージファイルを公開すると、パッケージが存在しない場合は作成されます。

前提条件：

  • APIで認証する必要があります。デプロイトークンで認証する場合は、write_package_registry スコープで設定する必要があります。パーソナルアクセストークンまたはプロジェクトアクセストークンで認証する場合は、api スコープで設定する必要があります。
  • 同じパッケージ名とバージョンで複数のファイルをアップロードしようとする場合、この API エンドポイントを連続して呼び出す必要があります。新しいパッケージ名とバージョンに複数のファイルを同時にアップロードしようとすると、パッケージを作成するためのリクエストのため、HTTP 500: Internal Server Error レスポンスで部分的に失敗する可能性があります。
PUT /projects/:id/packages/generic/:package_name/:package_version/:file_name?status=:status
属性種類必須説明
id整数/文字列yes プロジェクトのIDまたはURLエンコードされたパス。
package_name文字列です。yesパッケージ名。小文字 (a-z)、大文字 (A-Z)、数字 (0-9)、ドット (.)、ハイフン (-)、アンダースコア (_) のみを含むことができます。
package_version文字列です。yesパッケージのバージョン。次の正規表現で検証します:\A(\.?[\w\+-]+\.?)+\z.Rubular でバージョン文字列をテストできます。
file_name文字列です。yesファイル名。小文字 (a-z)、大文字 (A-Z)、数字 (0-9)、ドット (.)、ハイフン (-)、アンダースコア (_) のみを含むことができます。
status文字列です。いいえパッケージのステータスです。default (デフォルト) またはhidden です。 非表示パッケージは UI やパッケージ API リストエンドポイントに表示されません。
select文字列です。いいえレスポンスのペイロード。デフォルトでは、レスポンスは空です。有効な値は以下のとおりです：このリクエストによって作成されたパッケージファイルレコードの詳細を返しますpackage_file。 package_file

リクエストボディにファイルコンテキストを指定します。

個人アクセストークンを使用したリクエスト例：

curl --header "PRIVATE-TOKEN: <your_access_token>" \
     --upload-file path/to/file.txt \
     "https://gitlab.example.com/api/v4/projects/24/packages/generic/my_package/0.0.1/file.txt"

属性なしのレスポンス例select ：

{
  "message":"201 Created"
}

属性付きのリクエスト例select = package_file ：

curl --header "PRIVATE-TOKEN: <your_access_token>" \
     --user "<username>:<Project Access Token>" \
     --upload-file path/to/file.txt \
     "https://gitlab.example.com/api/v4/projects/24/packages/generic/my_package/0.0.1/file.txt?select=package_file"

select = package_file 属性による応答例 ：

{
  "id": 1,
  "package_id": 1,
  "created_at": "2021-10-12T12:05:23.387Z",
  "updated_at": "2021-10-12T12:05:23.387Z",
  "size": 0,
  "file_store": 1,
  "file_md5": null,
  "file_sha1": null,
  "file_name": "file.txt",
  "file": {
    "url": "/6b/86/6b86b273ff34fce19d6b804eff5a3f5747ada4eaa22f1d49c01e52ddb7875b4b/packages/26/files/36/file.txt"
  },
  "file_sha256": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
  "verification_retry_at": null,
  "verified_at": null,
  "verification_failure": null,
  "verification_retry_count": null,
  "verification_checksum": null,
  "verification_state": 0,
  "verification_started_at": null,
  "new_file_path": null
}

同じ名前またはバージョンのパッケージの公開

既存のパッケージと同じ名前やバージョンのパッケージを公開すると、新しいパッケージファイルが既存のパッケージに追加されます。重複している汎用パッケージをインストールすると、GitLabは最新バージョンをダウンロードします。

UIやAPIを使って、既存パッケージの古いファイルにアクセスし、閲覧することができます。これらの古いパッケージリビジョンを削除するには、Packages APIかUIの使用を検討してください。

ジェネリックパッケージの重複を許可しない

ユーザーがジェネリックパッケージを重複して公開しないようにするには、GraphQL APIまたは UI を使用します。

UI では

  1. 左のサイドバーで、Search（検索）を選択するか、Go to（移動）を選択してグループを探します。
  2. 設定 > パッケージとレジストリを選択します。
  3. パッケージの重複]テーブルの[一般]行で、[重複を許可]トグルをオフにします。
  4. オプション。例外] テキストボックスに、許可するパッケージの名前とバージョンに一致する正規表現を入力します。

変更は自動的に保存されます。

パッケージファイルのダウンロード

パッケージファイルをダウンロード

複数のパッケージの名前、バージョン、ファイル名が同じ場合は、最新のものが取得されます。

前提条件：

  • APIで認証する必要があります。デプロイトークンで認証する場合は、read_package_registry またはwrite_package_registry スコープで設定する必要があります。
GET /projects/:id/packages/generic/:package_name/:package_version/:file_name
属性種類必須説明
id整数/文字列yes プロジェクトのIDまたはURLエンコードされたパス。
package_name文字列です。yesパッケージ名。
package_version文字列です。yesパッケージのバージョン。
file_name文字列です。yesファイル名。

ファイルコンテキストはレスポンスボディで提供されます。レスポンスのコンテントタイプはapplication/octet-stream です。

個人アクセストークンを使用したリクエストの例です：

curl --header "PRIVATE-TOKEN: <your_access_token>" \
     "https://gitlab.example.com/api/v4/projects/24/packages/generic/my_package/0.0.1/file.txt"

HTTP Basic認証を使用したリクエスト例：

curl --user "user:<your_access_token>" \
     "https://gitlab.example.com/api/v4/projects/24/packages/generic/my_package/0.0.1/file.txt"

CI/CDによる汎用パッケージの発行

GitLab CI/CDで汎用パッケージを扱うには、コマンドで個人アクセストークンの代わりにCI_JOB_TOKEN 。

使用例：

image: curlimages/curl:latest

stages:
  - upload
  - download

upload:
  stage: upload
  script:
    - 'curl --header "JOB-TOKEN: $CI_JOB_TOKEN" --upload-file path/to/file.txt "${CI_API_V4_URL}/projects/${CI_PROJECT_ID}/packages/generic/my_package/0.0.1/file.txt"'

download:
  stage: download
  script:
    - 'wget --header="JOB-TOKEN: $CI_JOB_TOKEN" ${CI_API_V4_URL}/projects/${CI_PROJECT_ID}/packages/generic/my_package/0.0.1/file.txt'

PowerShell で Windows Runner を使用する場合、upload およびdownload ステージでcurl の代わりにInvoke-WebRequest またはInvoke-RestMethod を使用する必要があります。

使用例：

upload:
  stage: upload
  script:
    - Invoke-RestMethod -Headers @{ "JOB-TOKEN"="$CI_JOB_TOKEN" } -InFile path/to/file.txt -uri "${CI_API_V4_URL}/projects/${CI_PROJECT_ID}/packages/generic/my_package/0.0.1/file.txt" -Method put

汎用パッケージサンプルプロジェクト

Write CI-CD Variables in Pipelineプロジェクトには、GitLab CI/CD で汎用パッケージを作成、アップロード、ダウンロードするためのサンプルが含まれています。

また、ジェネリックパッケージのセマンティックバージョンを管理する方法も示しています：CI/CD変数に格納し、それを取得し、インクリメントし、ダウンロードのテストが正しく動作したときにCI/CD変数に書き戻します。

トラブルシューティング

S3への大容量ファイルのアップロードで内部サーバーエラーが発生します。

S3互換のオブジェクトストレージでは、1回のPUTリクエストのサイズが5GBに制限されています。オブジェクトストレージの接続設定で、aws_signature_version が2 に設定されている場合、5 GB の制限を超えるサイズのパッケージファイルを公開しようとすると、HTTP 500: Internal Server Error レスポンスが返されることがあります。

S3 に大きなファイルを公開するときにHTTP 500: Internal Server Error 応答を受け取る場合は、aws_signature_version を4 に設定してください：

# Consolidated Object Storage settings
gitlab_rails['object_store']['connection'] = {
  # Other connection settings
  'aws_signature_version' => '4'
}
# OR 
# Storage-specific form settings
gitlab_rails['packages_object_store_connection'] = {
  # Other connection settings
  'aws_signature_version' => '4'
}