Maven仮想レジストリ

Maven仮想レジストリは、単一の、よく知られたURLを使用して、GitLab内の複数の外部レジストリからパッケージを管理および配布します。

Maven仮想レジストリを使用して、以下を行います:

• バーチャルレジストリを作成します。
• バーチャルレジストリを、パブリックおよびプライベートアップストリームレジストリに接続します。
• 構成されたアップストリームからパッケージをプルするようにMavenクライアントを構成します。
• 利用可能なアップストリームのキャッシュエントリを管理します。

このアプローチにより、長期にわたってパッケージのパフォーマンスが向上し、Mavenパッケージの管理が容易になります。

バーチャルレジストリとアップストリームレジストリの管理に関する一般的な情報については、Virtual registryを参照してください。

前提要件

Maven仮想レジストリを使用する前に:

• バーチャルレジストリを使用するためのprerequisitesをレビューします。

Maven仮想レジストリを使用する場合は、次の制限事項に注意してください:

• トップレベルグループごとに最大20個のMaven仮想レジストリを作成できます。
• 指定されたMaven仮想レジストリに設定できるアップストリームは20個のみです。
• 技術的な理由により、proxy_download設定は、オブジェクトストレージ設定で構成されている値に関係なく、強制的に有効になります。
• Geoサポートは実装されていません。その開発状況はissue 473033で確認できます。

仮想レジストリを管理する

グループの仮想レジストリを管理します。

APIを使用することもできます。

仮想レジストリを表示します

バーチャルレジストリを表示するには:

1. 左側のサイドバーで、検索または移動先を選択して、グループを見つけます。このグループはトップレベルにある必要があります。
2. 左側のサイドバーで、デプロイ > バーチャルレジストリを選択します。

Maven仮想レジストリを作成します

Maven仮想レジストリを作成するには:

1. 左側のサイドバーで、検索または移動先を選択して、グループを見つけます。このグループはトップレベルにある必要があります。
2. 左側のサイドバーで、デプロイ > バーチャルレジストリを選択します。
3. レジストリを作成を選択します。
4. 名前とオプションの説明を入力します。
5. Mavenレジストリを作成を選択します。

バーチャルレジストリを編集する

既存のバーチャルレジストリを編集するには:

1. 左側のサイドバーで、検索または移動先を選択して、グループを見つけます。このグループはトップレベルにある必要があります。
2. 左側のサイドバーで、デプロイ > バーチャルレジストリを選択します。
3. レジストリタイプで、View registries（レジストリを表示）を選択します。
4. 編集するレジストリの行で、編集 ( ) を選択します。
5. 変更を加えて、変更を保存を選択します。

仮想レジストリを削除する

仮想レジストリを削除するには:

1. 左側のサイドバーで、検索または移動先を選択して、グループを見つけます。このグループはトップレベルにある必要があります。
2. 左側のサイドバーで、デプロイ > バーチャルレジストリを選択します。
3. レジストリタイプで、View registries（レジストリを表示）を選択します。
4. Registries（レジストリ）タブの、削除するレジストリの行で、編集 ( ) を選択します。
5. レジストリの削除を選択します。
6. 確認ダイアログで、削除を選択します。

アップストリームレジストリを管理する

バーチャルレジストリ内のアップストリームレジストリを管理します。

アップストリームレジストリを表示する

アップストリームレジストリを表示するには:

1. 左側のサイドバーで、検索または移動先を選択して、グループを見つけます。このグループはトップレベルにある必要があります。
2. 左側のサイドバーで、デプロイ > バーチャルレジストリを選択します。
3. レジストリタイプで、View registries（レジストリを表示）を選択します。
4. アップストリームタブを選択して、利用可能なすべてのアップストリームを表示します。

Mavenアップストリームレジストリを作成します

バーチャルレジストリに接続するためのMavenアップストリームレジストリを作成します。

前提要件:

• バーチャルレジストリが必要です。詳細については、レジストリを作成を参照してください。

Mavenアップストリームレジストリを作成するには:

1. 左側のサイドバーで、検索または移動先を選択して、グループを見つけます。このグループはトップレベルにある必要があります。
2. 左側のサイドバーで、デプロイ > バーチャルレジストリを選択します。
3. レジストリタイプで、View registries（レジストリを表示）を選択します。
4. Registries（レジストリ）タブで、レジストリを選択します。
5. アップストリームの追加を選択します。バーチャルレジストリに既存のアップストリームがある場合は、ドロップダウンリストから次のいずれかを選択します:
   • アップストリームを構成するには、新しいアップストリームを作成します。
   • 既存のアップストリームをリンク > Select existing upstream（既存のアップストリームを選択）。
     1. ドロップダウンリストから、アップストリームを選択します。
6. Mavenアップストリームレジストリを構成します:
   • 名前を入力します。
   • アップストリームのURLを入力します。
   • オプション。説明を入力します。
   • オプション。ユーザー名とパスワードを入力します。ユーザー名とパスワードの両方を含めるか、どちらも含まないようにする必要があります。設定されていない場合、パブリック（匿名）リクエストはアップストリームへのアクセスに使用されます。
7. アーティファクトのキャッシュ期間とメタデータのキャッシュ期間を設定します。
   • アーティファクトとメタデータのキャッシュ期間は、デフォルトで24時間です。0に設定すると、キャッシュエントリチェックが無効になります。
8. アップストリームを作成を選択します。

アップストリームをMaven Centralに接続する場合:

• アップストリームのURLには、次のURLを入力します:

  https://repo1.maven.org/maven2

• アーティファクトのキャッシュ期間とメタデータのキャッシュ期間は、時間を0に設定します。Maven Centralファイルはイミュータブルです。

キャッシュの有効期間設定の詳細については、Set the cache validity periodを参照してください。

アップストリームレジストリを編集する

アップストリームレジストリを編集するには:

1. 左側のサイドバーで、検索または移動先を選択して、グループを見つけます。このグループはトップレベルにある必要があります。
2. 左側のサイドバーで、デプロイ > バーチャルレジストリを選択します。
3. レジストリタイプで、View registries（レジストリを表示）を選択します。
4. アップストリームタブを選択します。
5. 編集するアップストリームの行で、編集 ( ) を選択します。
6. 変更を加えて、変更を保存を選択します。

アップストリームレジストリの順序を変更する

アップストリームレジストリの順序によって、パッケージに対してクエリが実行される優先順位が決まります。バーチャルレジストリは、リクエストされたパッケージが見つかるまで、アップストリームを上から下に検索します。

アップストリームレジストリの順序を変更するには:

1. 左側のサイドバーで、検索または移動先を選択して、グループを見つけます。このグループはトップレベルにある必要があります。
2. 左側のサイドバーで、デプロイ > Virtual registries（バーチャルレジストリ）を選択します。
3. レジストリタイプで、レジストリを選択します。
4. Registries（レジストリ）タブで、レジストリを選択します。
5. アップストリームで、アップストリームを並べ替えるには、アップストリームを上に移動またはアップストリームを下に移動を選択します。

アップストリームの順序付けに関するベストプラクティス:

• 内部パッケージを優先するために、プライベートレジストリをパブリックレジストリの前に配置します。
• より高速または信頼性の高いレジストリをリストの上位に配置します。
• パブリックな依存関係のフォールバックとして、パブリックレジストリを最後に配置します。

アップストリームの順序の詳細については、Upstream prioritizationを参照してください。

キャッシュされたパッケージを表示する

アップストリームレジストリからキャッシュされたパッケージを表示するには:

1. 左側のサイドバーで、検索または移動先を選択して、グループを見つけます。このグループはトップレベルにある必要があります。
2. 左側のサイドバーで、デプロイ > バーチャルレジストリを選択します。
3. レジストリタイプで、レジストリを選択します。
4. アップストリームタブで、アップストリームを選択します。
5. キャッシュされたパッケージのキャッシュメタデータを表示します。

キャッシュエントリを削除する

キャッシュエントリを削除するには:

1. 左側のサイドバーで、検索または移動先を選択して、グループを見つけます。このグループはトップレベルにある必要があります。
2. 左側のサイドバーで、デプロイ > バーチャルレジストリを選択します。
3. レジストリタイプで、レジストリを選択します。
4. Registries（レジストリ）タブで、レジストリを選択します。
5. アップストリームの横にある全てのキャッシュのクリアを選択します。
   • 特定のキャッシュエントリを削除するには、アップストリームの横にあるキャッシュをクリアを選択します。

キャッシュエントリを削除すると、次回バーチャルレジストリがそのファイルのリクエストを受信したときに、リクエストを満たすことができるアップストリームを見つけるために、アップストリームのリストを再度たどります。

キャッシュエントリの詳細については、Caching systemを参照してください。

Maven仮想レジストリを使用します

バーチャルレジストリを作成したら、バーチャルレジストリを介して依存関係をプルするようにMavenクライアントを構成する必要があります。

Mavenクライアントでの認証

バーチャルレジストリエンドポイントは、次のいずれかのトークンで使用できます:

• パーソナルアクセストークン。
• 検討対象のバーチャルレジストリをホストするトップレベルグループのグループデプロイトークン。
• 検討対象のバーチャルレジストリをホストするトップレベルグループのグループアクセストークン。
• CIジョブトークン。

トークンには、次のいずれかのスコープが必要です:

• api
• read_virtual_registry

アクセストークンとCIジョブトークンはユーザーに解決されます。解決されたユーザーは、次のいずれかである必要があります:

• guestの最小アクセスレベルを持つトップレベルグループの直接のメンバー。
• GitLabインスタンス管理者。
• トップレベルグループに含まれるプロジェクトのいずれかの直接のメンバー。

Mavenクライアントを構成する

Maven仮想レジストリは、次のMavenクライアントをサポートしています:

• mvn
• gradle
• sbt

Mavenクライアント構成で仮想レジストリを宣言する必要があります。

すべてのクライアントが認証されている必要があります。クライアント認証には、カスタムヘッダーまたは基本認証を使用できます。各クライアントに対して、以下の構成のいずれかを使用する必要があります。

<settings>
  <servers>
    <server>
      <id>gitlab-maven</id>
      <configuration>
        <httpHeaders>
          <property>
            <name>REPLACE_WITH_NAME</name>
            <value>REPLACE_WITH_TOKEN</value>
          </property>
        </httpHeaders>
      </configuration>
    </server>
  </servers>
</settings>

<repositories>
  <repository>
    <id>gitlab-maven</id>
    <url>https://gitlab.example.com/api/v4/virtual_registries/packages/maven/<registry_id></url>
  </repository>
</repositories>

<settings>
  <servers>
    ...
  </servers>
  <mirrors>
    <mirror>
      <id>central-proxy</id>
      <name>GitLab proxy of central repo</name>
      <url>https://gitlab.example.com/api/v4/virtual_registries/packages/maven/<registry_id></url>
      <mirrorOf>central</mirrorOf>
    </mirror>
  </mirrors>
</settings>

gitLabPrivateToken=REPLACE_WITH_YOUR_TOKEN

resolvers += ("gitlab" at "<endpoint_url>")

credentials += Credentials("GitLab Virtual Registry", "<host>", "<username>", "<token>")