- Mavenリポジトリの有効化
- Maven入門
- Gradleを使い始めるには
- GitLabパッケージレジストリをMavenリモートとして追加
- GitLab Maven リポジトリの URL を使用するようにプロジェクトを設定します。
- パッケージのアップロード
- パッケージのインストール
- パッケージの削除
- GitLab CI/CDによるMavenパッケージの作成
- トラブルシューティング
GitLab Mavenリポジトリ
GitLab Premium11.3で導入されました。
GitLabMavenリポジトリを使用すると、すべてのプロジェクトはMavenアーティファクトを保存するための独自のスペースを持つことができます。
Mavenリポジトリの有効化
Packages 機能を有効にすると、デフォルトですべての新規プロジェクトで Maven リポジトリが使用できるようになります。 既存のプロジェクトで有効にする場合、または無効にする場合は、次の手順に従います:
- プロジェクトの[設定]>[一般]>[権限]に移動します。
- パッケージ機能を検索し、有効または無効にします。
- 変更を有効にするには、[変更を保存]をクリックします。
すると、左のサイドバーに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
引数は以下の通り:
-
DgroupId
Mavenの命名規則に従ってください。 -
DartifactId
DgroupId
の末尾に付加される 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)
}
}
}
デプロイトークンによる認証
デプロイトークンで認証するには、デプロイトークンを作成する際にスコープを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
ファイルにrepository
とdistributionManagement
セクションを追加する必要があります。上記の手順に従っているのなら、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
をドメイン名に置き換えてください。
group%2Fproject
)またはプロジェクトのID(例:42
)のいずれかを使用できます。ただし、アップロードに使用できるのはプロジェクトのIDのみです。グループレベルのMavenエンドポイント
多くのパッケージに依存している場合、各パッケージに固有の URL を持つrepository
セクションを含めるのは非効率的かもしれません。 代わりに、1 つの GitLab グループ内に保存されているすべての Maven パッケージに対してグループレベルのエンドポイントを使用できます。 アクセス権を持つパッケージのみがダウンロード可能になります。
グループレベルエンドポイントはどのようなパッケージ名でも動作するため、インスタンスレベルエンドポイントに比べてネーミングの柔軟性があります。 しかし、GitLabはグループ内のパッケージ名の一意性を保証しません。 同じパッケージ名とパッケージバージョンを持つ2つのプロジェクトが存在する可能性があります。 その結果、GitLabはより新しい方を提供します。
以下の例では、pom.xml
のrepository
セクションがどのようになるかを示しています。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
をドメイン名に置き換えてください。
インスタンスレベルのMavenエンドポイント
多くのパッケージに依存している場合、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.xml
のrepository
セクションがどのようになるかを示しています。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
をドメイン名に置き換えてください。
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 から取得されたことを確認する同じダウンロードメッセージが表示されるはずです。
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
ブランチが更新されるたびに新しいパッケージを作成する方法を示しています:
-
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>
-
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をハードコードすることができます。 -
.gitlab-ci.yml
ファイルにdeploy
ジョブを追加します:deploy: image: maven:3.3.9-jdk-8 script: - 'mvn deploy -s ci_settings.xml' only: - master
-
これらのファイルをリポジトリにプッシュします。
次にdeploy
ジョブが実行されると、ci_settings.xml
がユーザーのホームロケーション(この場合、Docker コンテナで実行されるため、ユーザーはroot
です)にコピーされ、Maven は設定された CI 環境変数を利用します。
Gradleを使用したGitLab CI/CDによるMavenパッケージの作成
以下の例は、master
ブランチが更新されるたびに新しいパッケージを作成する方法を示しています:
-
GradleでのCIジョブトークンによる認証」で説明されているように、ジョブトークン認証を使用していることを確認してください。
-
.gitlab-ci.yml
ファイルにdeploy
ジョブを追加します:deploy: image: gradle:latest script: - 'gradle publish' only: - master
-
これらのファイルをリポジトリにプッシュします。
次にdeploy
ジョブが実行されると、ci_settings.xml
がユーザーのホームロケーションにコピーされ(この場合、Docker コンテナで実行されるため、ユーザーはroot
です)、Maven は設定された CI 環境変数を使用します。
バージョン検証
バージョン文字列は、以下の正規表現を使って検証されます。
\A(\.?[\w\+-]+\.?)+\z
この正規表現エディターで正規表現をいじったり、バージョン文字列を試すことができます。
トラブルシューティング
便利なMavenコマンドラインオプション
GitLab CI/CDで作業をするときに便利なMavenコマンドラインオプションがいくつかあります。
-
3.6.1では、
-ntp,--no-transfer-progress
オプションが追加されました。あるいは、-B,--batch-mode
または、より低レベルのロギングの変更を見てください。 -
POM ファイル (
-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'
Maven設定の確認
settings.xml
ファイルに関連する CI 内のイシューが発生した場合は、スクリプトタスクやジョブを追加して、効果的な設定を検証するとよいでしょう。
helpプラグインは環境変数などのシステムプロパティも提供できます:
mvn-settings:
script:
- 'mvn help:effective-settings'
package:
script:
- 'mvn help:system'
- 'mvn package'