GitLab Mavenリポジトリ

GitLab Premium11.3で導入されました

GitLabMavenリポジトリを使用すると、すべてのプロジェクトはMavenアーティファクトを保存するための独自のスペースを持つことができます。

GitLab Maven Repository

Mavenリポジトリの有効化

メモ:このオプションは、GitLab管理者がMavenリポジトリのサポートを有効にしている場合にのみ使用できます。

Packages 機能を有効にすると、デフォルトですべての新規プロジェクトで Maven リポジトリが使用できるようになります。 既存のプロジェクトで有効にする場合、または無効にする場合は、次の手順に従います:

  1. プロジェクトの[設定]>[一般]>[権限]に移動します。
  2. パッケージ機能を検索し、有効または無効にします。
  3. 変更を有効にするには、[変更を保存]をクリックします。

すると、左のサイドバーにPackages & Registries セクションが表示されます。 次に、GitLab Maven リポジトリでプロジェクトをオーソライズするように設定しなければなりません。

Maven入門

このセクションでは、Mavenのインストールとパッケージのビルドについて説明します。 これは、Mavenパッケージのビルドに慣れていない場合に役立つクイックスタートです。 すでにMavenを使用しており、独自のパッケージをビルドする方法を理解している場合は、次のセクションに進みます。

MavenリポジトリはGradleでもうまく動作します。 Gradleプロジェクトをセットアップしたい場合は、Gradleを使い始めるに進んでください。

Mavenのインストール

最低限必要なバージョンは以下の通りです:

  • Java 11.0.5 以上
  • Maven 3.6 以上

maven.apache.orgの指示に従って、ローカル開発環境用のMavenをダウンロードしてインストールします。 インストールが完了したら、ターミナルでMavenを実行して使用できることを確認します:

mvn --version

以下のようなものが出力されるはずです:

Apache Maven 3.6.1 (d66c9c0b3152b2e69ee9bac180bb8fcc8e6af555; 2019-04-04T20:00:29+01:00)
Maven home: /Users/<your_user>/apache-maven-3.6.1
Java version: 12.0.2, vendor: Oracle Corporation, runtime: /Library/Java/JavaVirtualMachines/jdk-12.0.2.jdk/Contents/Home
Default locale: en_GB, platform encoding: UTF-8
OS name: "mac os x", version: "10.15.2", arch: "x86_64", family: "mac"

プロジェクトの作成

完全なJavaプロジェクトの作成方法を理解することはこのガイドの範囲外ですが、以下の手順に従ってGitLabパッケージレジストリに公開できる新しいプロジェクトを作成することができます。

ターミナルを開き、環境にプロジェクトを保存するディレクトリを作成することから始めます。 ディレクトリの中から、以下のMavenコマンドを実行して、新しいパッケージを初期化します:

mvn archetype:generate -DgroupId=com.mycompany.mydepartment -DartifactId=my-project -DarchetypeArtifactId=maven-archetype-quickstart -DinteractiveMode=false

引数は以下の通り:

  • DgroupIdMavenの命名規則に従ってください。
  • DartifactIdDgroupIdの末尾に付加される JAR の名前。
  • DarchetypeArtifactIdプロジェクトの初期構造を作成するために使用されるアーキタイプ。
  • DinteractiveModeバッチモードでプロジェクトを作成します(オプション)。

コマンドを実行すると、プロジェクトが正常にセットアップされたことを示す以下のメッセージが表示されるはずです:

...
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time:  3.429 s
[INFO] Finished at: 2020-01-28T11:47:04Z
[INFO] ------------------------------------------------------------------------

このコマンドを実行した場所に、DartifactId パラメータと一致する新しいディレクトリが表示されるはずです(この場合、my-projectとなります)。

Gradleを使い始めるには

このセクションでは、GradleのインストールとJavaプロジェクトの初期化について説明します。 これは、Gradleを初めて使用する場合に役立つクイックスタートです。 Gradleをすでに使用しており、独自のパッケージをビルドする方法を理解している場合は、次のセクションに進んでください。

Gradleのインストール

インストールが必要なのは、新しいGradleプロジェクトを作成する場合のみです。gradle.orgの指示に従って、ローカル開発環境用のGradleをダウンロードしてインストールしてください。

ターミナルでGradleが使えることを確認してください:

gradle -version

既存の Gradle プロジェクトを使用する場合、インストールは必要ありません。代わりにプロジェクトディレクトリでgradlew (Linux) またはgradlew.bat (Windows) を実行するだけです。

以下のようなものが出力されるはずです:

------------------------------------------------------------
Gradle 6.0.1
------------------------------------------------------------

Build time:   2019-11-18 20:25:01 UTC
Revision:     fad121066a68c4701acd362daf4287a7c309a0f5

Kotlin:       1.3.50
Groovy:       2.5.8
Ant:          Apache Ant(TM) version 1.10.7 compiled on September 1 2019
JVM:          11.0.5 (Oracle Corporation 11.0.5+10)
OS:           Windows 10 10.0 amd64

Gradleでのプロジェクトの作成

Gradle で完全な Java プロジェクトを作成する方法を理解することはこのガイドの範囲外ですが、以下の手順に従って GitLab パッケージレジストリに公開できる新しいプロジェクトを作成することができます。

ターミナルを開き、環境にプロジェクトを保存するディレクトリを作成することから始めます。 ディレクトリの中から、以下のMavenコマンドを実行して、新しいパッケージを初期化します:

gradle init

出力は次のようになります。

Select type of project to generate:
  1: basic
  2: application
  3: library
  4: Gradle plugin
Enter selection (default: basic) [1..4]

3 と入力すると、新しいライブラリープロジェクトが作成されます:

Select implementation language:
  1: C++
  2: Groovy
  3: Java
  4: Kotlin
  5: Scala
  6: Swift

3 と入力すると、新しいJavaライブラリ・プロジェクトが作成されます:

Select build script DSL:
  1: Groovy
  2: Kotlin
Enter selection (default: Groovy) [1..2]

1 を選択して、Groovy DSLで記述される新しいJavaライブラリプロジェクトを作成します:

Select test framework:
  1: JUnit 4
  2: TestNG
  3: Spock
  4: JUnit Jupiter

1 を選択して、JUnit 4 テストライブラリでプロジェクトを初期化します:

Project name (default: test):

プロジェクト名を入力するか、エンターキーを押してディレクトリ名をプロジェクト名として使用します。

GitLabパッケージレジストリをMavenリモートとして追加

次のステップは、GitLab パッケージレジストリを Maven リモートとして追加することです。 プロジェクトが非公開の場合や、GitLab に Maven アーティファクトをアップロードする場合は、作成者の認証情報も必要になります。個人アクセストークン、CI ジョブトークンデプロイトークンのみがサポートされています。 通常のユーザー名/パスワード認証情報は機能しません。

個人アクセストークンによる認証

個人アクセストークンで認証するには、作成時にスコープをapi に設定し、Maven または Gradle 設定ファイルに追加します。

Mavenでの個人アクセストークンによる認証

settings.xml ファイルに対応するセクションを追加してください:

<settings>
  <servers>
    <server>
      <id>gitlab-maven</id>
      <configuration>
        <httpHeaders>
          <property>
            <name>Private-Token</name>
            <value>REPLACE_WITH_YOUR_PERSONAL_ACCESS_TOKEN</value>
          </property>
        </httpHeaders>
      </configuration>
    </server>
  </servers>
</settings>

Gradleでの個人アクセストークンによる認証

以下の内容でファイル~/.gradle/gradle.properties

gitLabPrivateToken=REPLACE_WITH_YOUR_PERSONAL_ACCESS_TOKEN

build.gradleファイルにリポジトリセクションを追加してください:

repositories {
    maven {
        url "https://<gitlab-url>/api/v4/groups/<group>/-/packages/maven"
        name "GitLab"
        credentials(HttpHeaderCredentials) {
            name = 'Private-Token'
            value = gitLabPrivateToken
        }
        authentication {
            header(HttpHeaderAuthentication)
        }
    }
}

これで、プロジェクトにMavenアーティファクトをアップロードできるようになります。

CIジョブトークンによる認証

GitLab CI/CDを使っている場合は、個人アクセストークンの代わりにCIジョブトークンを使うことができます。

MavenのCIジョブトークンによる認証

CI ジョブ トークンで認証するには、settings.xml ファイルに対応するセクションを追加します:

<settings>
  <servers>
    <server>
      <id>gitlab-maven</id>
      <configuration>
        <httpHeaders>
          <property>
            <name>Job-Token</name>
            <value>${env.CI_JOB_TOKEN}</value>
          </property>
        </httpHeaders>
      </configuration>
    </server>
  </servers>
</settings>

GitLabCI/CDを使ってMavenパッケージを作成する方法については、こちらをご覧ください。

GradleでのCIジョブトークンによる認証

CI ジョブ トークンで認証するには、build.gradleファイルに repositories セクションを追加します:

repositories {
    maven {
        url "https://<gitlab-url>/api/v4/groups/<group>/-/packages/maven"
        name "GitLab"
        credentials(HttpHeaderCredentials) {
            name = 'Job-Token'
            value = '${CI_JOB_TOKEN}'
        }
        authentication {
            header(HttpHeaderAuthentication)
        }
    }
}

デプロイトークンによる認証

GitLab Premium13.0から導入されました

デプロイトークンで認証するには、デプロイトークンを作成する際にスコープをapi に設定し、Maven または Gradle 設定ファイルに追加します。

Mavenでのデプロイトークンによる認証

settings.xml ファイルに対応するセクションを追加してください:

<settings>
  <servers>
    <server>
      <id>gitlab-maven</id>
      <configuration>
        <httpHeaders>
          <property>
            <name>Deploy-Token</name>
            <value>REPLACE_WITH_YOUR_DEPLOY_TOKEN</value>
          </property>
        </httpHeaders>
      </configuration>
    </server>
  </servers>
</settings>

Gradleでのデプロイトークンによる認証

デプロイトークンで認証するには、build.gradleファイルに repositories セクションを追加します:

repositories {
    maven {
        url "https://<gitlab-url>/api/v4/groups/<group>/-/packages/maven"
        name "GitLab"
        credentials(HttpHeaderCredentials) {
            name = 'Deploy-Token'
            value = '<deploy-token>'
        }
        authentication {
            header(HttpHeaderAuthentication)
        }
    }
}

GitLab Maven リポジトリの URL を使用するようにプロジェクトを設定します。

GitLab からパッケージをダウンロードしたりアップロードしたりするには、pom.xml ファイルにrepositorydistributionManagement セクションを追加する必要があります。上記の手順に従っているのなら、my-project/pom.xml ファイルに以下の情報を追加する必要があります。

あなたのワークフローやMavenパッケージの量に応じて、Mavenパッケージ用のGitLabエンドポイントを使用するようにプロジェクトを設定する3つの方法があります:

  • プロジェクトレベル:同じGitLabグループの下にないいくつかのMavenパッケージがある場合に便利です。
  • グループレベル:同じGitLabグループの下に多くのMavenパッケージがある場合に便利です。
  • インスタンスレベル:異なるGitLabグループや独自のネームスペースに多くのMavenパッケージがある場合に便利です。
注:distributionManagement セクションにパッケージをアップロードするには、どのような場合でもプロジェクト固有の URL が必要です。

プロジェクトレベルのMavenエンドポイント

以下の例は、pom.xmlの関連するrepository セクションが Maven でどのように見えるかを示しています:

<repositories>
  <repository>
    <id>gitlab-maven</id>
    <url>https://gitlab.com/api/v4/projects/PROJECT_ID/packages/maven</url>
  </repository>
</repositories>
<distributionManagement>
  <repository>
    <id>gitlab-maven</id>
    <url>https://gitlab.com/api/v4/projects/PROJECT_ID/packages/maven</url>
  </repository>
  <snapshotRepository>
    <id>gitlab-maven</id>
    <url>https://gitlab.com/api/v4/projects/PROJECT_ID/packages/maven</url>
  </snapshotRepository>
</distributionManagement>

Gradleの対応するセクションは次のようになります:

repositories {
    maven {
        url "https://gitlab.com/api/v4/projects/PROJECT_ID/packages/maven"
        name "GitLab"
    }
}

idは、 で定義したものと同じでなければなりません。settings.xml

PROJECT_ID 、プロジェクトのホームページに記載されているプロジェクトIDに置き換えてください。

GitLab をセルフマネジメントでインストールしている場合は、gitlab.com をドメイン名に置き換えてください。

注:アーティファクトの検索には、URLエンコードされたプロジェクトのパス(例:group%2Fproject)またはプロジェクトのID(例:42)のいずれかを使用できます。ただし、アップロードに使用できるのはプロジェクトのIDのみです。

グループレベルのMavenエンドポイント

GitLab Premium11.7から導入されました

多くのパッケージに依存している場合、各パッケージに固有の URL を持つrepository セクションを含めるのは非効率的かもしれません。 代わりに、1 つの GitLab グループ内に保存されているすべての Maven パッケージに対してグループレベルのエンドポイントを使用できます。 アクセス権を持つパッケージのみがダウンロード可能になります。

グループレベルエンドポイントはどのようなパッケージ名でも動作するため、インスタンスレベルエンドポイントに比べてネーミングの柔軟性があります。 しかし、GitLabはグループ内のパッケージ名の一意性を保証しません。 同じパッケージ名とパッケージバージョンを持つ2つのプロジェクトが存在する可能性があります。 その結果、GitLabはより新しい方を提供します。

以下の例では、pom.xmlrepository セクションがどのようになるかを示しています。distributionManagement セクションにパッケージをアップロードするには、プロジェクト固有の URL が必要です:

<repositories>
  <repository>
    <id>gitlab-maven</id>
    <url>https://gitlab.com/api/v4/groups/GROUP_ID/-/packages/maven</url>
  </repository>
</repositories>
<distributionManagement>
  <repository>
    <id>gitlab-maven</id>
    <url>https://gitlab.com/api/v4/projects/PROJECT_ID/packages/maven</url>
  </repository>
  <snapshotRepository>
    <id>gitlab-maven</id>
    <url>https://gitlab.com/api/v4/projects/PROJECT_ID/packages/maven</url>
  </snapshotRepository>
</distributionManagement>

Gradleの場合、対応するリポジトリセクションは次のようになります:

repositories {
    maven {
        url "https://gitlab.com/api/v4/groups/GROUP_ID/-/packages/maven"
        name "GitLab"
    }
}

idは、 で定義したものと同じでなければなりません。settings.xml

my-group をあなたのグループ名に、PROJECT_ID をプロジェクトのホームページに記載されているプロジェクトIDに置き換えてください。

GitLab をセルフマネジメントでインストールしている場合は、gitlab.com をドメイン名に置き換えてください。

注:アーティファクトの検索には、グループのURL エンコードされたパス(例:group%2Fsubgroup)またはグループの ID( 例:12)を使用できます。

インスタンスレベルのMavenエンドポイント

GitLab Premium11.7から導入されました

多くのパッケージに依存している場合、repository セクションに各パッケージに固有の URL を含めるのは非効率的かもしれません。代わりに、GitLab に保存されているすべての Maven パッケージのインスタンスレベルのエンドポイントを使用すると、アクセス可能なパッケージがダウンロードできるようになります。

プロジェクトと同じパスを持つパッケージだけがインスタンスレベルのエンドポイントを経由して公開されることに注意してください。

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

以下の例では、pom.xmlrepository セクションがどのようになるかを示しています。distributionManagement セクションにパッケージをアップロードするには、プロジェクト固有の URL が必要です:

<repositories>
  <repository>
    <id>gitlab-maven</id>
    <url>https://gitlab.com/api/v4/packages/maven</url>
  </repository>
</repositories>
<distributionManagement>
  <repository>
    <id>gitlab-maven</id>
    <url>https://gitlab.com/api/v4/projects/PROJECT_ID/packages/maven</url>
  </repository>
  <snapshotRepository>
    <id>gitlab-maven</id>
    <url>https://gitlab.com/api/v4/projects/PROJECT_ID/packages/maven</url>
  </snapshotRepository>
</distributionManagement>

Gradleの対応するリポジトリセクションは次のようになります:

repositories {
    maven {
        url "https://gitlab.com/api/v4/packages/maven"
        name "GitLab"
    }
}

idは、 で定義したものと同じでなければなりません。settings.xml

PROJECT_ID 、プロジェクトのホームページに記載されているプロジェクトIDに置き換えてください。

GitLab をセルフマネジメントでインストールしている場合は、gitlab.com をドメイン名に置き換えてください。

注:アーティファクトの検索には、URLエンコードされたプロジェクトのパス(例:group%2Fproject)またはプロジェクトのID(例:42)のいずれかを使用できます。ただし、アップロードに使用できるのはプロジェクトのIDのみです。

パッケージのアップロード

リモートと認証を設定し、プロジェクトを構成したら、自分のプロジェクトからMavenアーティファクトをアップロードするテストを行います。

Mavenを使用したアップロード

mvn deploy

デプロイが成功すれば、ビルド成功のメッセージが再び表示されるはずです:

...
[INFO] BUILD SUCCESS
...

アップロードが正しいレジストリにアップロードされたことも確認できるはずです:

Uploading to gitlab-maven: https://gitlab.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プラグインmaven-publish をプラグインセクションに追加します:

plugins {
    id 'java'
    id 'maven-publish'
}

publishing

publishing {
    publications {
        library(MavenPublication) {
            from components.java
        }
    }
    repositories {
        maven {
            url "https://gitlab.com/api/v4/projects/<PROJECT_ID>/packages/maven"
            credentials(HttpHeaderCredentials) {
                name = "Private-Token"
                value = gitLabPrivateToken // the variable resides in ~/.gradle/gradle.properties
            }
            authentication {
                header(HttpHeaderAuthentication)
            }
        }
    }
}

PROJECT_ID 、プロジェクトのホームページに記載されているプロジェクトIDに置き換えてください。

パブリッシュタスクを実行します:

gradle publish

その後、プロジェクトの「パッケージとレジストリ」ページに移動し、アップロードされたアーティファクトを確認したり、削除したりすることができます。

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

GitLab パッケージレジストリからパッケージをインストールするには、上記のようにリモートと認証を設定する必要があります。 これが完了したら、パッケージをインストールする方法は二通りあります。

でMavenを使用してインストールします。mvn install

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

<dependency>
  <groupId>com.mycompany.mydepartment</groupId>
  <artifactId>my-project</artifactId>
  <version>1.0-SNAPSHOT</version>
</dependency>

次に、プロジェクト内で以下を実行します:

mvn install

すべてが正しく設定されていれば、GitLabパッケージレジストリからダウンロードされた依存関係が表示されるはずです:

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

インストールmvn dependency:get

パッケージをインストールする2つ目の方法は、Mavenコマンドを直接使用することです。 プロジェクトディレクトリ内で、実行します:

mvn dependency:get -Dartifact=com.nickkipling.app:nick-test-app:1.1-SNAPSHOT

プロジェクトが GitLab Package Registry から取得されたことを確認する同じダウンロードメッセージが表示されるはずです。

ヒント:XMLブロックとMavenコマンドはどちらもパッケージの詳細ページからコピー&ペーストすることができ、素早く簡単にインストールすることができます。

Gradleを使ったインストール

build.gradleのdependenciesセクションに依存関係を追加します:

dependencies {
    implementation 'com.mycompany.mydepartment:my-project:1.0-SNAPSHOT'
}

パッケージの削除

プロジェクトページのPackagesビューで、赤いゴミ箱アイコンをクリックするか、パッケージ詳細ページのDeleteボタンをクリックすると、パッケージを削除できます。

GitLab CI/CDによるMavenパッケージの作成

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

Mavenを使ったGitLab CI/CDでのMavenパッケージの作成

以下の例は、master ブランチが更新されるたびに新しいパッケージを作成する方法を示しています:

  1. Mavenのsettings.xml ファイルとして機能するci_settings.xml ファイルを作成します。pom.xml ファイルで定義したのと同じIDでサーバーセクションを追加します。 例えば、私たちの場合はgitlab-maven

    <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>${env.CI_JOB_TOKEN}</value>
              </property>
            </httpHeaders>
          </configuration>
        </server>
      </servers>
    </settings>
    
  2. pom.xml ファイルに以下が含まれていることを確認してください:

    <repositories>
      <repository>
        <id>gitlab-maven</id>
        <url>https://gitlab.com/api/v4/projects/${env.CI_PROJECT_ID}/packages/maven</url>
      </repository>
    </repositories>
    <distributionManagement>
      <repository>
        <id>gitlab-maven</id>
        <url>https://gitlab.com/api/v4/projects/${env.CI_PROJECT_ID}/packages/maven</url>
      </repository>
      <snapshotRepository>
        <id>gitlab-maven</id>
        <url>https://gitlab.com/api/v4/projects/${env.CI_PROJECT_ID}/packages/maven</url>
      </snapshotRepository>
    </distributionManagement>
    
    ヒント:MavenにCI環境変数を利用させるか、プロジェクトIDをハードコードすることができます。
  3. .gitlab-ci.yml ファイルにdeploy ジョブを追加します:

    deploy:
      image: maven:3.3.9-jdk-8
      script:
        - 'mvn deploy -s ci_settings.xml'
      only:
        - master
    
  4. これらのファイルをリポジトリにプッシュします。

次にdeploy ジョブが実行されると、ci_settings.xml がユーザーのホームロケーション(この場合、Docker コンテナで実行されるため、ユーザーはroot です)にコピーされ、Maven は設定された CI 環境変数を利用します。

Gradleを使用したGitLab CI/CDによるMavenパッケージの作成

以下の例は、master ブランチが更新されるたびに新しいパッケージを作成する方法を示しています:

  1. GradleでのCIジョブトークンによる認証」で説明されているように、ジョブトークン認証を使用していることを確認してください。

  2. .gitlab-ci.yml ファイルにdeploy ジョブを追加します:

    deploy:
      image: gradle:latest
      script:
        - 'gradle publish'
      only:
        - master
    
  3. これらのファイルをリポジトリにプッシュします。

次にdeploy ジョブが実行されると、ci_settings.xml がユーザーのホームロケーションにコピーされ(この場合、Docker コンテナで実行されるため、ユーザーはroot です)、Maven は設定された CI 環境変数を使用します。

バージョン検証

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

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

この正規表現エディターで正規表現をいじったり、バージョン文字列を試すことができます。

トラブルシューティング

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

GitLab CI/CDで作業をするときに便利なMavenコマンドラインオプションがいくつかあります。

Maven設定の確認

settings.xml ファイルに関連する CI 内のイシューが発生した場合は、スクリプトタスクやジョブを追加して、効果的な設定を検証するとよいでしょう。

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

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

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