[小ネタ] GitHub Pagesを使ってMavenの簡易的なリポジトリを作ってみた

2020.05.29

はじめに

Javaのプロジェクトで使われるビルドツールであるMavenのリポジトリについて調べる機会がありました。 その際、GitHub Pagesを使ってリポジトリを作れることがわかったので、試してみました。

環境

次のような環境・バーションで実施しました。
また、本記事のMavenの操作は、すべてCLIを想定しています。

$ sw_vers
ProductName:	Mac OS X
ProductVersion:	10.15.4
BuildVersion:	19E287
$ java -version
openjdk version "1.8.0_242"
OpenJDK Runtime Environment Corretto-8.242.08.2 (build 1.8.0_242-b08)
OpenJDK 64-Bit Server VM Corretto-8.242.08.2 (build 25.242-b08, mixed mode)
$ mvn -version
Apache Maven 3.6.1  (snip)

※Maven自体が未インストールの場合はHomebrew等で追加して下さい。

事前準備

Mavenのコマンドを使用してJavaプロジェクトの雛形を作っておきます。

$ mvn archetype:generate \
  -DarchetypeArtifactId=maven-archetype-quickstart \
  -DinteractiveMode=false \
  -DgroupId=hoge \
  -DartifactId=fuga

hoge, fugaの所は適当な名前に置換して下さい。

ここでは単純にHello Wroldを出力させるpluginを作成します。

src/main/java/hoge/App.java

package hoge;

public class App {
    public App() {
        System.out.println( "Hello World!" );
    }
}

設定方法

具体的には、以下のGitHubのpluginを利用します。
github/maven-plugins

そのためにまずGitHubに専用のリポジトリを作成しておきます。 この時、git initし、READMEファイルをpushしておくと、以下のGitHub Pagesのオプションを選択できるようになります。 ここでmasterを選択します。

ついでGitHubのトークンを取得し、以下のようにMavenの設定ファイル~/.m2/settings.xmlへ追記します。

~/.m2/settings.xml

<?xml version="1.0" encoding="UTF-8"?>
<settings xmlns="http://maven.apache.org/SETTINGS/1.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.0.0 http://maven.apache.org/xsd/settings-1.0.0.xsd">
  <servers>
    <server>
      <id>github</id>
      <password>{GitHub Token}</password>
    </server>
  </servers>
</settings>

ここからは、pom.xmlの編集作業です。 site-maven-pluginを追加し、configuration中にGitHubの情報を追加します。

pom.xml

<plugin>
  <groupId>com.github.github</groupId>
  <artifactId>site-maven-plugin</artifactId>
  <version>0.12</version>
  <executions>
    <execution>
      <goals>
        <goal>site</goal>
      </goals>
      <phase>site</phase>
      <configuration>
        <server>github</server>
        <repositoryName>Repository-Name</repositoryName>
        <repositoryOwner>GitHub-Account</repositoryOwner>
        <message>Creating site</message>
        <outputDirectory>mvn-repo</outputDirectory>
        <branch>refs/heads/master</branch>
        <path></path>
        <merge>ture</merge>
      </configuration>
    </execution>
  </executions>
</plugin>

GitHub-AccountRepository-Nameはご自身のアカウント/リポジトリに置き換えてください。

GitHub Pagesに関する設定としては上記のpluginのみですが、併せてmaven-site-pluginmaven-project-info-reports-pluginも指定しておきます。

pom.xml

<plugin>
  <groupId>org.apache.maven.plugins</groupId>
  <artifactId>maven-site-plugin</artifactId>
  <version>3.7.1</version>
  <configuration>
    <locales>en</locales>
    <inputEncoding>UTF-8</inputEncoding>
    <outputEncoding>UTF-8</outputEncoding>
    <outputDirectory>mvn-repo</outputDirectory>
  </configuration>
  <dependencies>
    <dependency>
      <groupId>org.apache.maven.doxia</groupId>
      <artifactId>doxia-site-renderer</artifactId>
      <version>1.9.1</version>
    </dependency>
  </dependencies>
</plugin>
<plugin>
  <groupId>org.apache.maven.plugins</groupId>
  <artifactId>maven-project-info-reports-plugin</artifactId>
  <version>3.0.0</version>
</plugin>

さらに、今回の方法では、mvn deploy実行時に一旦ローカルのディレクトリに出力し、それをmvn siteでアップロードすると言う手順を踏みたいため、以下の様にdistributionManagementを追記します。

pom.xml

<distributionManagement>
  <repository>
    <id>internal.repo</id>
    <name>Temporary Repository</name>
    <url>file:///full/path/to/output/directory</url>
  </repository>
</distributionManagement>

file:///full/path/to/output/directoryを適切なディレクトリ名に置き換えてください。
※既述のpluginの設定ではディレクトリ名はmvn-repoとなっています

最後に、pom.xmlに以下の情報も忘れずに書いておきます。

pom.xml

<properties>
  <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
  <github.global.server>github</github.global.server>
</properties>

コンパイルおよびアップロード

以下のゴールを順番に実施して、最後のmvn siteでGitHubへアップロードします。

mvn clean    # 予めcleanしておきます。
mvn compile  # コンパイルします。
mvn deploy   # 一旦ローカルに出力します。
mvn site     # アップロードします。

ここでは、各コマンドの出力内容については割愛させて頂きますが、mvn siteCreating blobsのところで少し時間がかかると思います。

使用方法

上記のライブラリを使う側の設定は、例えば以下のような感じです。
テストプロジェクトを作成してhoge.Appをimportします。

UserSide.java

package piyo;
import hoge.App;

public class UserSide {
    public static void main( String[] args ) {
		App app = new App();
    }
}

こちらのpom.xmlには下記のようにdependencyrepositoryを追加して下さい。

pom.xml

<dependencies>
  <dependency>
    <groupId>hoge</groupId>
    <artifactId>fuga</artifactId>
    <version>1.0-SNAPSHOT</version>
  </dependency>
</dependencies>

<repositories>
  <repository>
    <id>github</id>
    <name>my github repository</name>
    <url>https://raw.githubusercontent.com/{GitHub-Account}/{Repository-Nmae}/master/</url>
  </repository>
</repositories>

※{GitHub-Account}と{Repository-Nmae}はそれぞれご修正下さい。

ハマりどころ

ローカルキャッシュ

Mavenのpluginは(特に設定をしていなければ)~/.m2/repositoryにキャッシュされます。 そのため、該当するgroupId/artifactIdのディレクトリを別の場所に退避させることで、(同一バージョンであっても)コンパイル時にダウンロードし直す事ができます。

GitHubアカウント

GitHubのReal Nameの欄が未記入だとエラーになります。アカウントを本名で使用されていない方などはご注意下さい。

さいごに

最後まで読んで頂きありがとうございました。
実際の運用面ではいくつかハードルがあるかもしれませんが、GitHub Pagesにリポジトリを作る過程自体は、Mavenの理解を深める上では役立つのではないかと思いました。
どなたかに届けば幸いです。