たなかこういちの資料室

システム開発に携わる筆者があれこれ試したことや学んだことについてのまとめ

GitHubにMavenリポジトリーを作成し、運用する手順

GitHubMavenリポジトリーを作成し運用する手順をまとめました。この手順に則れば下記二点が実現されます。
 
(1) 普通に「mvn deploy」することで、自分のMavenプロジェクトを、GitHub上に用意したMavenリポジトリーへ配置すること。
 
(2) GitHub上のMavenリポジトリーに登録したプロジェクトを、他のMavenプロジェクトの<dependency>より参照すること。
 
本記事の手順は下記条件の元で実施、動作確認しています。
 
- 2015年9月28日に実施
- Maven 3.3.3を使用(※maven-deploy-plugin 2.7を使用)
- GitHub Site Plugin 0.12を使用
 
概要
 
下記記事にまさにその方法が議論されていました!先達に感謝です。基本的に同記事の議論に則りつつ、pom.xmlの記述方法を取りまとめました。
 
Stack Overflowより、"Hosting a Maven repository on github":
 
上記記事に記される手法の要点を以下に示します。
 
GitHubが公式にリリースしているMaven Pluginである「GitHub Site Plugin」を使用する。
 
 
GitHub Site Pluginは、本来的には「Maven Site」を「GitHub Page」としてアップロードできるようにするものである。つまり、「mvn site:site」で生成されたドキュメント類をGitHubの「gh-pages」ブランチにpushすることが元来意図された用途である。
 
・それに対し、GitHub Site Pluginの構成およびmaven-deploy-pluginの構成に工夫をすることで、「mvn deploy」による生成物をGitHub上のリポジトリーへアップロードすることを実現した。
 
詳細
 
1. 「mvn deploy」の配置先となるような一時的なMavenローカルリポジトリーが、プロジェクト自身の"target"サブディレクトリー下に存在するというように、pom.xmlを構成します。
 
対象プロジェクトのpom.xmlに下記内容を記述することで、「mvn deploy」で、自プロジェクトの"target"サブディレクトリー下に展開される(一時的な)Mavenローカルリポジトリーに(も)、プロジェクト生成物が配置されるようになります。このMavenローカルリポジトリーが、maven-deploy-pluginとGitHub Site Pluginの橋渡しとなります。
 
-----(ここから)-----
<properties>
    <altDeploymentRepository>staging-maven-repo::default::file://${project.build.directory}/staging-maven-repo</altDeploymentRepository>
</properties>
-----(ここまで)-----
 
※プロパティaltDeploymentRepositoryは、maven-deploy-pluginが参照します。
※上記記述例中の"staging-maven-repo"の部分には任意の名称を用いることができます。
 
2. pom.xmlにて、GitHub Site Pluginの構成をします。
 
対象プロジェクトのpom.xmlに、下記のようにGitHub Site Pluginに関する記述を追記してください。記述の要点は下記4つです。
 
・<outputDirectory>に、前項「1.」でaltDeploymentRepositoryに指定したパスと同じパスを指定します。
GitHubユーザー、リポジトリー、ブランチを任意に指定します。
※ブランチには、masterを含む任意のブランチを指定することができます。
※下記記述例中の<branch>、<repositoryName>、<repositoryOwner>の内容は、それぞれご自身のものに置き換えてください。
・<server>に、settings.xmlに記述する認証情報参照用のidを指定します。下記記述例中の"github.tanaka9230"を任意の値に置き変えてください。この値には、複数の認証情報(、つまり、複数GitHubアカウント)を使い分けるようなケースを想定して、GitHubユーザー名を含めるようにした方がよいと思います。
・<execution>で、GitHub Site Pluginの「site」ゴールを「deploy」フェーズで実行するように変更します。
 
-----(ここから)-----
<build>
    <plugins>
        <plugin>
            <groupId>com.github.github</groupId>
            <artifactId>site-maven-plugin</artifactId>
            <version>0.12</version>
            <configuration>
                <message>Maven artifacts for ${project.build.finalName}</message><!-- commit message -->
                <merge>true</merge><!-- to merge with existing artifacts' tree -->
                <noJekyll>true</noJekyll><!-- to disable web page processing -->
                <outputDirectory>${project.build.directory}/staging-maven-repo</outputDirectory><!-- to be matched to 'altDeploymentRepository' property -->
                <branch>refs/heads/master</branch><!-- GitHub branch name -->
                <repositoryName>test-maven-repo</repositoryName><!-- GitHub repository name -->
                <repositoryOwner>tanaka9230</repositoryOwner><!-- GitHub user name -->
                <server>github.tanaka9230</server><!-- to be matched to the '/settings/servers/server/id' element in "settings.xml" -->
            </configuration>
            <executions>
                <execution>
                    <goals>
                        <goal>site</goal>
                    </goals>
                    <phase>deploy</phase>
                </execution>
            </executions>
        </plugin>
    </plugins>
</build>
-----(ここまで)-----
 
3. settings.xmlに、GitHub接続用認証情報の設定を追加します。
 
下記のように、Mavenのsettings.xmlの<server>要素にGitHub接続用の認証情報を記述します。<id>は「2.」における<server>要素と同じ値とします。複数の認証情報(、つまり、複数GitHubアカウント)を使い分けるようなケースを想定して、<id>の値には、GitHubユーザー名を含めるのがよいと思います。
 
-----(ここから)-----
<server>
    <id>github.tanaka9230</id>
    <username>YOUR_GITHUB_USERNAME</username>
    <password>YOUR_GITHUB_PASSWORD</password>
</server>
-----(ここまで)-----
 
以上を以って、「mvn deploy」を実行すると、構成したGitHubリポジトリーの指定したブランチに配置されます。
 
4. GitHub上のMavenリポジトリーに配置されたプロジェクトを<dependency>で参照するときは、参照する側のプロジェクトのpom.xmlの<repository>要素に、GitHub上のリポジトリーについての構成を記述します。
 
GitHub上のMavenリポジトリーに配置されたプロジェクトを<dependency>で参照する側のプロジェクトのpom.xmlに、下記のようにリポジトリーの情報を記述します。記述の要点は以下の二つです。
 
・<id>要素は任意です。settings.xmlの<server>要素の<id>と一致させる必要はありません。ただし、下記記述例の様に、GitHubユーザー名、GitHubリポジトリー名、必要ならさらにブランチ名を含めておくのがよいと思います。
・<url>要素は下記記述例に倣ってください。URLのドメインは"raw.github.com"です。ディレクトリー部分は「GitHubユーザー名」+「リポジトリー名」+「ブランチ名」です。ブランチ名部分も必須です。
 
-----(ここから)-----
<repositories>
    <repository>
        <id>github.tanaka9230.test-maven-repo</id>
        <name>Koichi TANAKA's Test Maven Repository</name>
        <url>https://raw.github.com/tanaka9230/test-maven-repo/master</url>
    </repository>
</repositories>
-----(ここまで)-----
 
実例
 
次のURLに実際に作成したサンプルプロジェクトを置きました。
 
"test-java-app" - Test Maven Project
 
GitHubリポジトリー"test-java-app"に置かれているものは、一つのjarを生成するMavenプロジェクトであり、MavenリポジトリーではありませんMavenリポジトリーとしては、GitHubリポジトリー"test-maven-repo"を用意しました。
 
"test-maven-repo" - Test Maven Repository
 
Mavenプロジェクト"test-java-app"を(ローカルにpullしてきた後、)「mvn deploy」すれば、GitHubリポジトリー"test-maven-repo"に配置されるよう構成されています。(※現状配置済み状態です。)
 
◆注意◆
・この記事に示されるサンプルプロジェクトのダウンロード、改変、再配布など一切自由です。
・サンプルは、ご自身のGitHubアカウントを作成して、ご自身のGitHubリポジトリーでお試しください。pom.xml内のGitHubのユーザー名、リポジトリー名は、ご自身のものへ書き換えてください。加えて、試行環境に導入してあるMavenのsettings.xmlの<server>要素に、ご自身のGitHub認証情報を記述する必要があります。書き換え方は前節「詳細」をご参照ください。
 
次のURLは、先ほどの"test-java-app"への<dependency>参照のあるプロジェクトのサンプルです。
 
"test-another-java-app" - Test Maven Project with Dependencies
 
この"test-another-java-app"プロジェクトのpom.xmlには、<dependencies>に"test-java-app"が記述されていて、<repositories>にGitHubリポジトリー"test-maven-repo"の情報が記述されています。このプロジェクトを(ローカルにpullしてきた後、)「mvn package」すれば、依存プロジェクト"test-java-app"がリポジトリー"test-maven-repo"よりダウンロードされる様子が分かります。
 
-----(ここから)-----
mvn package
[INFO] Scanning for projects...
[INFO]                                                                         
[INFO] ------------------------------------------------------------------------
[INFO] Building test-another-java-app 0.0
[INFO] ------------------------------------------------------------------------
[INFO] 
[INFO] --- maven-resources-plugin:2.6:resources (default-resources) @ test-another-java-app ---
[INFO] Using 'UTF-8' encoding to copy filtered resources.
[INFO] Copying 2 resources
[INFO] 
[INFO] --- maven-compiler-plugin:3.1:compile (default-compile) @ test-another-java-app ---
・・・(略)・・・
[INFO] --- maven-jar-plugin:2.4:jar (default-jar) @ test-another-java-app ---
[INFO] Building jar: /Users/kou/Projects/Tests/test-anoher-java-app/target/test-another-java-app-0.0.jar
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time: 7.498 s
[INFO] Finished at: 2015-09-28T02:18:59+09:00
[INFO] Final Memory: 19M/183M
[INFO] ------------------------------------------------------------------------
-----(ここまで)-----
 
"test-another-java-app"自体も、「mvn deploy」でリポジトリー"test-maven-repo"に配置されるよう構成しています。(※現状配置済み状態です。)
 
注意
 
ひとつ注意を。GitHubMavenリポジトリーとして運用するのは、新たなサーバーを建てる必要がなくお手軽だというのが唯一のメリットだと理解しています。あくまで小規模に個人ユースレベルで運用する程度に収めておいた方が、いろいろな面で無難に思えます。
 
◆以上