GitHubにMavenリポジトリを構築してライブラリを公開する方法

投稿者 : OSCA

初心者でも参加できる「WEBエンジニア勉強会 #13」(東京都,渋谷)、05月24日(金) に開催! 詳しくはイベント詳細ページをご覧ください。

 Java 言語を利用したプロジェクトで jar ライブラリを作成した場合、「作成した jar ライブラリをどのように配布するか?」はとても悩ましい問題です。 本稿では、Maven リポジトリを GitHub 上に作成して jar ライブラリを配布する方法について解説します。 後記しますが、ここで紹介する方法は「正攻法」ではなく、ツールの使い方を工夫した「ハック」であることに注意してください。 (本稿はこちらの記事などを参考に情報を整理したものです)

本稿のゴール

 詳しい説明を始める前に、本稿のゴールを整理します。 本稿で解説する方法を実現すると、次のことができるようになります。

実現できること

  • mvn deploy コマンドを実行すると、jar ライブラリが GitHub にプッシュされる。
  • GitHub上にプッシュされたライブラリは誰からも参照できる。

なぜGitHubにMavenリポジトリを構築するのか?

 昨今のJavaプロジェクトでは、ライブラリの管理・依存関係の解決に Maven を利用することが多く、ビルドシステムに Gradle を利用している場合も Maven リポジトリから依存ライブラリを取得することが多いでしょう。 そのため、独自に作成したライブラリも何らかの Maven リポジトリで管理すると便利です。

 Maven には、公式の「Maven Central」というリポジトリがありますが、Maven Central リポジトリにライブラリを登録するには申請のプロセスが必要で少し手間がかかります。 作成したライブラリを全世界的に公開したい場合には Maven Central に公開するのが良いとは思いますが、もっとライトに公開したい場合にはハードルが高い気がします。

 代替の方法として、独自の Maven リポジトリを構築する方法があります。 独自の Maven リポジトリを構築するためのソフトウェアが世の中にはあり、本サイトの Apache Maven のページでは「Sonatype Nexus」というソフトウェアの導入手順を紹介しています。 このような「Sonatype Nexus」などで構築した独自のリポジトリをインターネットで公開するのも一つの方法ではありますが、インターネットにオープンに公開するということは、今後ずっとメンテナンスし続ける使命を背負うことでもあります。 守秘義務のあるライブラリを社内LANの中に限って公開する場合などは「Sonatype Nexus」などの製品は良いでしょうが、不特定多数からのアクセスを許すようにインターネットに公開するには、あまりにも負担が大きすぎます。

 そこで GitHub 上に Maven リポジトリを構築できると便利です。 GitHub を Maven リポジトリと利用することで、サーバーメンテナンスやアクセス負荷の心配から解放されます。

どのような仕組みなのか?

 ご存知の通り、本来 GitHub のリポジトリはソースコードを公開するためのものです。 そのため「GitHub 上に Maven リポジトリを構築するのは、正しいやり方なのか?」ということが疑問が湧くかと思います。 ここでは、どのような仕組みで GitHub 上に Maven リポジトリを公開するのかを説明します。

GitHub Maven Plugins

 GitHub には、GitHub Pages という機能があります。 GitHub 上で HTML, CSS などを利用した静的サイトをホスティングしてくれる機能です。 この GitHub Pages に Maven プロジェクトの成果物である site をアップロードしてくれるプラグイン 「GitHub Maven Plugins」を GitHub が公式で公開しています。 このプラグインを利用することが、本稿の”肝”になります。

 本来の「GitHub Maven Plugins」は、mvn site:site コマンドの実行の結果で出力される target/site 内の成果物を、Gitリポジトリの gh-pages ブランチにプッシュし、GitHub Pages のページとして公開できるようにするためのものです。

 しかしアップロードする対象ファイルを target/site ではなく mvn deploy コマンドで生成されるファイルに変更し、かつ gh-pages ブランチではない任意のブランチにプッシュさせてしまうことで、GitHub で Maven リポジトリをホストさせることを実現します。

リポジトリのファイルへの直アクセス

 GitHub のリポジトリにプッシュされたファイルには、以下のようなURLでアクセスできることも、仕組みを理解する上で重要な要素です。

https://raw.githubusercontent.com/ユーザ名/リポジトリ名/ブランチ名/ファイル名

 つまり、とあるリポジトリの特定のブランチに mvn deploy コマンドで生成されるファイルをプッシュすることで Maven リポジトリとして利用できるということです。

設定してみよう

 それでは、ここから実際に GitHub で Maven リポジトリを公開するための設定について解説します。

デプロイ先の変更

 mvn deploy コマンドを実行した際に Maven が参照できるリポジトリを pom.xml に宣言します。 ここでは、ローカルの target/mvn-repo フォルダをリポジトリとして宣言します。 id の名前は何でも良いですが、下の設定で使いますので注意してください。 name はどんなものでも良いです。 プロパティ project.build.directory は Maven で予約された変数であり、target ディレクトリを表します。

<distributionManagement>
  <repository>
    <id>internal.repo</id>
    <name>Temporary Staging Repository</name>
    <url>file://${project.build.directory}/mvn-repo</url>
  </repository>
</distributionManagement>

 また、同時に maven-deploy-plugin の設定も変更し、上で宣言したリポジトリに対して成果物をデプロイするように pom.xml で指定します。 altDeploymentRepository の値の書式は「id::layout::url」で、上で宣言したリポジトリのID、リポジトリのレイアウト、リポジトリのURIを記述します。

<plugins>
  <plugin>
    <artifactId>maven-deploy-plugin</artifactId>
      <version>2.8.2</version>
      <configuration>
         <altDeploymentRepository>internal.repo::default::file://${project.build.directory}/mvn-repo</altDeploymentRepository>
    </configuration>
  </plugin>
</plugins>

GitHubアカウントの設定

 次に GitHub のアカウント情報を設定します。 ファイル ~/.m2/settings.xml に、次の例のように <server> の情報を追加します。 (YOUR-USERNAME, YOUR-PASSWORD は、あなたのGitHubアカウント情報に合わせて設定してください。)

<settings>
  <servers>
    <server>
      <id>github</id>
      <username>YOUR-USERNAME</username>
      <password>YOUR-PASSWORD</password>
    </server>
  </servers>
</settings>

 上で設定した GitHub アカウントを利用するように、pom.xml に次のようなプロパティを設定します。 指定している値は、settings.xml に記載したIDです。

<properties>
  <github.global.server>github</github.global.server>
</properties>

GitHub Maven Plugins の設定

 つづいて、GitHub Maven Plugins の Site プラグイン(site-maven-plugin) の設定を変更します。 Site プラグインの「site」ゴールを「deploy」フェーズで実行するように変更してあげます。 configuration の設定内容は後記しますが、本来は site 成果物を GitHub Pages にプッシュするためのものですが、Maven リポジトリを扱うように設定を変更しています。

<plugin>
  <groupId>com.github.github</groupId>
  <artifactId>site-maven-plugin</artifactId>
  <version>0.12</version>
  <configuration>
    <message>Maven artifacts for ${project.version}</message>
    <noJekyll>true</noJekyll>
    <merge>true</merge>
    <outputDirectory>${project.build.directory}/mvn-repo</outputDirectory>
    <branch>refs/heads/mvn-repo</branch>
    <includes><include>**/*</include></includes>
    <repositoryName>YOUR-REPOSITORY-NAME</repositoryName>
    <repositoryOwner>YOUR-GITHUB-USERNAME</repositoryOwner>
  </configuration>
  <executions>
    <execution>
      <goals>
        <goal>site</goal>
      </goals>
      <phase>deploy</phase>
    </execution>
  </executions>
</plugin>

 configuration タグでの設定内容は、以下の通りです。

項目説明
messageGitにコミットする際のメッセージ
noJekyll常に .nojekyll ファイルを作成するか否か
merge既存の成果物にマージ(上書き)させるか否か
outputDirectory成果物が出力されているディレクトリ
repositoryNameリポジトリ名
repositoryOwnerリポジトリのユーザ名
branchブランチ名
includes処理対象とするファイルの指定

ライブラリの公開

 それでは mvn deploy コマンドを実行して、ライブラリを GitHub のリポジトリにコミットしてみましょう。 指定した GitHub のリポジトリに jar ファイルがコミットされることで jar ライブラリが公開されます。

ライブラリの利用

 GitHub で公開した jar ライブラリを利用する場合は、pom.xml の <repositories> に以下のように <repository> を追加すれば利用することができます。

<project ...>
  <repositories>
    ...
    <repository>
      <id>github</id>
      <name>my github repository</name>
      <url>https://raw.githubusercontent.com/user_name/repository_name/branch_name/</url>
    </repository>
   ...
  </repositories>
  ...
</project>

 id と name はそれぞれ分かりやすい値を設定してください。 肝心なのは url で、上で指定した GitHub のリポジトリを指定します。

おわりに

 本稿では、Maven リポジトリを GitHub 上に作成して jar ライブラリを配布する方法について解説しました。 ご自身で作成されているOSSライブラリの公開などに、ぜひ活用してみてください。

Apache Maven の目次へ戻る

著者 : OSCA

OSCA

Java, PHP 系のWEBエンジニア。 WEBエンジニア向けコミュニティ「WEBエンジニア勉強会」を主催。
個人として何か一つでも世の中の多くの人に使ってもらえるものを作ろうと日々奮闘中。
@engineer_osca