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

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

Maven パッケージマネージャークライアントが使用する特定の API エンドポイントのドキュメントについては、Maven API ドキュメントを参照してください。

サポートされているクライアント

  • mvn.Mavenパッケージをビルドする方法について説明します。
  • gradle.Gradleパッケージをビルドする方法を学びます。
  • sbt.

GitLab パッケージレジストリへの公開

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

パッケージを公開するにはトークンが必要です。実現しようとしていることに応じて、利用可能なトークンは異なります。詳しくはトークンに関するガイダンスをレビューしてください。

トークンを作成し、後で使用するために保存してください。

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

クライアント設定の編集

クライアントの設定ファイルに認証の詳細を追加する必要があります。

mvn
トークンの種類名前はトークン
個人アクセストークンPrivate-Tokenトークンをそのまま貼り付けるか、トークンを保持する環境変数を定義します。
デプロイトークンDeploy-Tokenトークンをそのまま貼り付けるか、トークンを保持する環境変数を定義します。
CIジョブトークンJob-Token${CI_JOB_TOKEN}
note
<name> フィールドは選択したトークンと同じ名前にする必要があります。

settings.xml ファイルに以下のセクションを追加してください。

<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>
gradle
トークンの種類名前はトークン
個人アクセストークンPrivate-Tokenトークンをそのまま貼り付けるか、トークンを保持する環境変数を定義します。
デプロイトークンDeploy-Tokenトークンをそのまま貼り付けるか、トークンを保持する環境変数を定義します。
CIジョブトークンJob-TokenSystem.getenv("CI_JOB_TOKEN")
note
<name> フィールドは選択したトークンと同じ名前にする必要があります。

GRADLE_USER_HOME ディレクトリ に、以下の内容のファイルgradle.properties を作成します:

gitLabPrivateToken=REPLACE_WITH_YOUR_TOKEN

build.gradle ファイルにrepositories セクションを追加します:

  • Groovy DSLに:

     repositories {
         maven {
             url "https://gitlab.example.com/api/v4/groups/<group>/-/packages/maven"
             name "GitLab"
             credentials(HttpHeaderCredentials) {
                 name = 'REPLACE_WITH_NAME'
                 value = gitLabPrivateToken
             }
             authentication {
                 header(HttpHeaderAuthentication)
             }
         }
     }
    
  • Kotlin DSLで:

     repositories {
         maven {
             url = uri("https://gitlab.example.com/api/v4/groups/<group>/-/packages/maven")
             name = "GitLab"
             credentials(HttpHeaderCredentials::class) {
                 name = "REPLACE_WITH_NAME"
                 value = findProperty("gitLabPrivateToken") as String?
             }
             authentication {
                 create("header", HttpHeaderAuthentication::class)
             }
         }
     }
    
sbt
トークンの種類名前はトークン
個人アクセストークンユーザーのユーザー名トークンをそのまま貼り付けるか、トークンを保持する環境変数を定義します。
デプロイトークンデプロイトークンのユーザー名。トークンをそのまま貼り付けるか、トークンを保持する環境変数を定義します。
CIジョブトークンgitlab-ci-tokensys.env.get("CI_JOB_TOKEN").get

SBTの認証は基本HTTP認証に基づいています。名前とパスワードを入力する必要があります。

note
名前フィールドには、選択したトークンに一致する名前を指定する必要があります。

sbt を使用して Maven GitLab パッケージレジストリからパッケージをインストールするには、Maven リゾルバを設定する必要があります。非公開または内部のプロジェクトやグループにアクセスする場合は、認証情報を設定する必要があります。リゾルバと認証の設定後、プロジェクト、グループ、またはネームスペースからパッケージをインストールできます。

build.sbt に以下の行を追加します:

resolvers += ("gitlab" at "<endpoint url>")

credentials += Credentials("GitLab Packages Registry", "<host>", "<name>", "<token>")

この例では:

  • <endpoint url>エンドポイントURLです。例:https://gitlab.example.com/api/v4/projects/<project_id>/packages/maven.
  • <host> はプロトコルスキームやポートを除いた<endpoint url> 内のホストです。例:gitlab.example.com.
  • <name><token> は上の表で説明されています。

命名規約

Maven パッケージをインストールするには、3 つのエンドポイントのいずれかを使用できます。パッケージをプロジェクトにパブリッシュする必要がありますが、選択したエンドポイントによって、パブリッシュのためにpom.xml ファイルに追加する設定が決まります。

3つのエンドポイントは次のとおりです:

  • プロジェクトレベル:Maven パッケージがいくつかあり、それらが同じ GitLab グループにない場合に使用します。
  • グループレベル:同じGitLabグループ内の多くの異なるプロジェクトのパッケージをインストールしたい場合に使用します。GitLabはグループ内のパッケージ名の一意性を保証しません。同じパッケージ名とパッケージバージョンを持つ2つのプロジェクトが存在する可能性があります。その結果、GitLabは新しい方を提供します。
  • インスタンスレベル:異なるGitLabグループや独自の名前空間に多くのパッケージがある場合に使います。

インスタンスレベルのエンドポイントでは、Maven のpom.xml の関連セクションが次のようになっていることを確認してください:

  <groupId>group-slug.subgroup-slug</groupId>
  <artifactId>project-slug</artifactId>

プロジェクトと同じパスを持つパッケージのみがインスタンスレベルエンドポイントによって公開されます。

プロジェクトPackageインスタンスレベルのエンドポイントが利用可能
foo/barfoo/bar/1.0-SNAPSHOTはい
gitlab-org/gitlabfoo/bar/1.0-SNAPSHOTなし
gitlab-org/gitlabgitlab-org/gitlab/1.0-SNAPSHOTはい

エンドポイントURL

エンドポイントのエンドポイントURLpom.xml 追加情報
プロジェクトhttps://gitlab.example.com/api/v4/projects/<project_id>/packages/maven gitlab.example.com をあなたのドメイン名に置き換えてください。<project_id> は、プロジェクトのホームページにあるプロジェクトIDに置き換えてください。
グループhttps://gitlab.example.com/api/v4/groups/<group_id>/-/packages/maven gitlab.example.com をドメイン名に置き換えてください。<group_id> をあなたのグループIDに置き換えてください(あなたのグループのホームページに記載されています)。
インスタンスhttps://gitlab.example.com/api/v4/packages/maven gitlab.example.com をドメイン名に置き換えてください。

公開用の設定ファイルを編集します。

クライアントの設定ファイルにパブリッシングの詳細を追加する必要があります。

mvn

どのエンドポイントを選択する場合でも、以下のものが必要です:

  • distributionManagement セクションにプロジェクト固有の URL。
  • repositorydistributionManagement セクション。

Maven のpom.xml の関連するrepository セクションは次のようになります:

<repositories>
  <repository>
    <id>gitlab-maven</id>
    <url><your_endpoint_url></url>
  </repository>
</repositories>
<distributionManagement>
  <repository>
    <id>gitlab-maven</id>
    <url>https://gitlab.example.com/api/v4/projects/<project_id>/packages/maven</url>
  </repository>
  <snapshotRepository>
    <id>gitlab-maven</id>
    <url>https://gitlab.example.com/api/v4/projects/<project_id>/packages/maven</url>
  </snapshotRepository>
</distributionManagement>
  • idsettings.xml](#edit-the-client-configuration)で定義した[です。
  • <your_endpoint_url> はどのエンドポイントを選ぶかによって異なります。
  • gitlab.example.com をドメイン名に置き換えてください。
gradle

Gradle を使ってパッケージを公開するには、次のようにします:

  1. Gradleプラグインmaven-publish をプラグインセクションに追加します:

    • Groovy DSLに:

       plugins {
           id 'java'
           id 'maven-publish'
       }
      
    • Kotlin DSLで:

       plugins {
           java
           `maven-publish`
       }
      
  2. publishing セクションを追加しました:

    • Groovy DSLに:

       publishing {
           publications {
               library(MavenPublication) {
                   from components.java
               }
           }
           repositories {
               maven {
                   url "https://gitlab.example.com/api/v4/projects/<PROJECT_ID>/packages/maven"
                   credentials(HttpHeaderCredentials) {
                       name = "REPLACE_WITH_TOKEN_NAME"
                       value = gitLabPrivateToken // the variable resides in $GRADLE_USER_HOME/gradle.properties
                   }
                   authentication {
                       header(HttpHeaderAuthentication)
                   }
               }
           }
       }
      
    • Kotlin DSLで:

       publishing {
           publications {
               create<MavenPublication>("library") {
                   from(components["java"])
               }
           }
           repositories {
               maven {
                   url = uri("https://gitlab.example.com/api/v4/projects/<PROJECT_ID>/packages/maven")
                   credentials(HttpHeaderCredentials::class) {
                       name = "REPLACE_WITH_TOKEN_NAME"
                       value =
                           findProperty("gitLabPrivateToken") as String? // the variable resides in $GRADLE_USER_HOME/gradle.properties
                   }
                   authentication {
                       create("header", HttpHeaderAuthentication::class)
                   }
               }
           }
       }
      

パッケージの公開

認証を設定し、公開用のエンドポイントを選択したら、プロジェクトに Maven パッケージを公開します。

mvn

Maven を使用してパッケージを公開するには、次の手順に従います:

mvn deploy

デプロイが成功すると、ビルド成功メッセージが表示されます:

...
[INFO] BUILD SUCCESS
...

また、パッケージが正しい場所に公開されたことも表示されるはずです:

Uploading to gitlab-maven: https://example.com/api/v4/projects/PROJECT_ID/packages/maven/com/mycompany/mydepartment/my-project/1.0-SNAPSHOT/my-project-1.0-20200128.120857-1.jar
gradle

パブリッシュタスクを実行してください:

gradle publish

プロジェクトのPackages and registriesページに移動し、パブリッシュされたパッケージを表示します。

パッケージのインストール

GitLabパッケージレジストリからパッケージをインストールするには、リモートの設定と認証が必要です。これが完了したら、プロジェクト、グループ、名前空間からパッケージをインストールできます。

複数のパッケージが同じ名前とバージョンである場合、パッケージをインストールすると、最近公開されたパッケージが取得されます。

mvn

mvn install を使ってパッケージをインストールするには :

  1. 依存関係を手動でプロジェクトpom.xml ファイルに追加します。先に作成した例を追加するには、XMLは次のようになります:

    <dependency>
      <groupId>com.mycompany.mydepartment</groupId>
      <artifactId>my-project</artifactId>
      <version>1.0-SNAPSHOT</version>
    </dependency>
    
  2. プロジェクトで以下を実行してください:

    mvn install
    

パッケージ・レジストリからパッケージがダウンロードされていることを示すメッセージが表示されるはずです:

Downloading from gitlab-maven: http://gitlab.example.com/api/v4/projects/PROJECT_ID/packages/maven/com/mycompany/mydepartment/my-project/1.0-SNAPSHOT/my-project-1.0-20200128.120857-1.pom

Mavendependency:get コマンド を直接使用してパッケージをインストールすることもできます。

  1. プロジェクトディレクトリで実行します:

    mvn dependency:get -Dartifact=com.nickkipling.app:nick-test-app:1.1-SNAPSHOT -DremoteRepositories=gitlab-maven::::<gitlab endpoint url>  -s <path to settings.xml>
    
    • <gitlab endpoint url> は GitLabエンドポイントの URL です。
    • <path to settings.xml>認証の詳細を含むsettings.xml ファイルへのパスです。
note
コマンド(gitlab-maven)とsettings.xml ファイルのリポジトリ ID は一致している必要があります。

パッケージ・レジストリからパッケージがダウンロードされていることを示すメッセージが表示されるはずです:

Downloading from gitlab-maven: http://gitlab.example.com/api/v4/projects/PROJECT_ID/packages/maven/com/mycompany/mydepartment/my-project/1.0-SNAPSHOT/my-project-1.0-20200128.120857-1.pom
gradle

gradle を使ってパッケージをインストールするには:

  1. 依存関係のセクションにbuild.gradle への依存関係を追加してください:

    • Groovy DSLに:

       dependencies {
           implementation 'com.mycompany.mydepartment:my-project:1.0-SNAPSHOT'
       }
      
    • Kotlin DSLで:

       dependencies {
           implementation("com.mycompany.mydepartment:my-project:1.0-SNAPSHOT")
       }
      
  2. プロジェクトで以下を実行してください:

    gradle install
    
sbt

sbt を使ってパッケージをインストールするには:

  1. build.sbtインライン依存関係を追加してください:

    libraryDependencies += "com.mycompany.mydepartment" % "my-project" % "8.4"
    
  2. プロジェクトで以下を実行してください:

    sbt update
    

役立つヒント

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

既存のパッケージと同じ名前とバージョンのパッケージを公開すると、新しいパッケージファイルが既存のパッケージに追加されます。UI や API を使って既存のパッケージの古いアセットにアクセスして表示することはできます。

古いバージョンのパッケージを削除するには、Packages API または UI の使用を検討してください。

Maven パッケージの重複を許可しないようにします。

GitLab 15.0 で必須ロールが開発者からメンテナーに変更されました。

ユーザーが重複した Maven パッケージを公開しないようにするには、GraphQl APIまたは UI を使用します。

UI では

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

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

Maven Centralへの転送要求

機能フラグ: デフォルトでは、この機能は自己管理では使用できません。利用可能にするには、管理者はmaven_central_request_forwarding という機能フラグを有効にします。この機能は、SaaSユーザーでは使用できません。

Mavenパッケージがパッケージレジストリで見つからない場合、要求はMaven Centralに転送されます。

機能フラグが有効な場合、管理者は継続的インテグレーションの設定でこの動作を無効にできます。

Maven 転送は、プロジェクトレベルとグループレベルのエンドポイントのみに制限されています。インスタンスレベルのエンドポイントには、その規約に従わないパッケージに使用できないようにする命名制限があり、また、サプライチェーンスタイルの攻撃に対するセキュリティリスクが高すぎます。

の追加設定mvn

mvnを使用する場合、GitLab から Maven Central のパッケージを要求するように Maven プロジェクトを設定する多くの方法があります。Maven リポジトリは特定の順序でクエリされます。デフォルトでは、Maven Centralは通常Super POMを通して最初にチェックされるので、GitLabはmaven-centralの前にクエリされるように設定する必要があります。

すべてのパッケージ要求が Maven Central ではなく GitLab に送られるようにするには、settings.xml<mirror> セクションを追加することで、中央リポジトリとして Maven Central を上書きすることができます:

<settings>
  <servers>
    <server>
      <id>central-proxy</id>
      <configuration>
        <httpHeaders>
          <property>
            <name>Private-Token</name>
            <value><personal_access_token></value>
          </property>
        </httpHeaders>
      </configuration>
    </server>
  </servers>
  <mirrors>
    <mirror>
      <id>central-proxy</id>
      <name>GitLab proxy of central repo</name>
      <url>https://gitlab.example.com/api/v4/projects/<project_id>/packages/maven</url>
      <mirrorOf>central</mirrorOf>
    </mirror>
  </mirrors>
</settings>

GitLab CI/CD で Maven パッケージを作成します。

Maven用パッケージリポジトリを使用するようにリポジトリを設定した後、新しいパッケージを自動的にビルドするようにGitLab CI/CDを設定することができます。

mvn

デフォルトブランチが更新されるたびに新しいパッケージを作成できます。

  1. Maven のsettings.xml ファイルとして機能するci_settings.xml ファイルを作成します。

  2. pom.xml ファイルで定義したのと同じ ID でserver セクションを追加します。例えば、gitlab-maven を ID として使用します:

    <settings xmlns="http://maven.apache.org/SETTINGS/1.1.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
      xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.1.0 http://maven.apache.org/xsd/settings-1.1.0.xsd">
      <servers>
        <server>
          <id>gitlab-maven</id>
          <configuration>
            <httpHeaders>
              <property>
                <name>Job-Token</name>
                <value>${CI_JOB_TOKEN}</value>
              </property>
            </httpHeaders>
          </configuration>
        </server>
      </servers>
    </settings>
    
  3. pom.xml ファイルに以下が含まれていることを確認します。この例に示すように、Mavenに定義済みのCI/CD変数を使用させるか、サーバーのホスト名とプロジェクトのIDをハードコードすることができます。

    <repositories>
      <repository>
        <id>gitlab-maven</id>
        <url>${CI_API_V4_URL}/projects/${CI_PROJECT_ID}/packages/maven</url>
      </repository>
    </repositories>
    <distributionManagement>
      <repository>
        <id>gitlab-maven</id>
        <url>${CI_API_V4_URL}/projects/${CI_PROJECT_ID}/packages/maven</url>
      </repository>
      <snapshotRepository>
        <id>gitlab-maven</id>
        <url>${CI_API_V4_URL}/projects/${CI_PROJECT_ID}/packages/maven</url>
      </snapshotRepository>
    </distributionManagement>
    
  4. .gitlab-ci.yml ファイルにdeploy ジョブを追加してください:

    deploy:
      image: maven:3.6-jdk-11
      script:
        - 'mvn deploy -s ci_settings.xml'
      rules:
        - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
    
  5. これらのファイルをリポジトリにプッシュしてください。

次にdeploy ジョブが実行されると、ci_settings.xml をユーザーのホームにコピーします。この例では

  • ジョブはDockerコンテナで実行されるため、ユーザーはroot
  • Mavenは設定されたCI/CD変数を使用します。
gradle

デフォルトブランチが更新されるたびにパッケージを作成できます。

  1. GradleのCIジョブトークンで認証します。

  2. .gitlab-ci.yml ファイルにdeploy ジョブを追加してください:

    deploy:
      image: gradle:6.5-jdk11
      script:
        - 'gradle publish'
      rules:
        - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
    
  3. リポジトリにファイルをコミットします。

パイプラインが成功すると、Maven パッケージが作成されます。

バージョンの検証

バージョン文字列は、以下の正規表現を使って検証されます。

\A(?!.*\.\.)[\w+.-]+\z

正規表現を試して、この正規表現エディターであなたのバージョン文字列を試すことができます。

便利なMavenコマンドラインオプション

GitLab CI/CDでタスクを実行するときに使えるMavenコマンドラインオプションがいくつかあります。

  • ファイル転送の進行状況は CI ログを読みにくくすることがあります。オプション-ntp,--no-transfer-progress3.6.1 で追加されました。あるいは、-B,--batch-mode やより低レベルのロギングの変更を見てください。

  • pom.xml ファイル (-f,--file) の場所を指定します:

     package:
       script:
         - 'mvn --no-transfer-progress -f helloworld/pom.xml package'
    
  • デフォルトの場所ではなく、ユーザー設定の場所 (-s,--settings) を指定します。-gs,--global-settings オプションもあります:

     package:
       script:
         - 'mvn -s settings/ci.xml package'
    

サポートされているCLIコマンド

GitLab Mavenリポジトリは以下のCLIコマンドをサポートしています:

mvn
  • mvn deploy:パッケージをパッケージレジストリに公開します。
  • mvn install:Mavenプロジェクトで指定されたパッケージをインストールします。
  • mvn dependency:get:特定のパッケージをインストールします。
gradle
  • gradle publish:パッケージをパッケージレジストリに公開します。
  • gradle install:Gradleプロジェクトで指定したパッケージをインストールします。

トラブルシューティング

パフォーマンスを向上させるために、クライアントはパッケージに関連するファイルをキャッシュします。イシューが発生した場合は、以下のコマンドでキャッシュをクリアしてください:

mvn
rm -rf ~/.m2/repository
gradle
rm -rf ~/.gradle/caches # Or replace ~/.gradle with your custom GRADLE_USER_HOME

ネットワークトレースログのレビュー

Maven リポジトリにイシューがある場合、ネットワークトレースログをレビューすることができます。

たとえば、mvn deploy を PAT トークンでローカルに実行し、これらのオプションを使用してみます:

mvn deploy \
-Dorg.slf4j.simpleLogger.log.org.apache.maven.wagon.providers.http.httpclient=trace \
-Dorg.slf4j.simpleLogger.log.org.apache.maven.wagon.providers.http.httpclient.wire=trace
caution
これらのオプションを設定すると、すべてのネットワークリクエストがログに記録され、大量の出力が生成されます。

Maven設定の確認

CI/CD 内でsettings.xml ファイルに関連するイシューが発生した場合、スクリプトタスクまたはジョブを追加して、効果的な設定を確認してください。

helpプラグインは環境変数を含むシステムプロパティも提供できます:

mvn-settings:
  script:
    - 'mvn help:effective-settings'

package:
  script:
    - 'mvn help:system'
    - 'mvn package'