Kengo's blog

Technical articles about original projects, JVM, Static Analysis and TypeScript.

Deploying Maven's site to GitHub Pages

 Are you using Maven's site feature? How about GitHub Pages? If you're using both of them, GitHub's site-maven-plugin helps you to host your site on Pages.
 MavenのsiteとGitHub Pagesを使っている方に朗報です。GitHub社がsiteをPagesにデプロイするMavenプラグインを公開しており、とても簡単に利用することができます。

Settings

 At first, write <plugin>...</plugin> in your pom.xml.
 まずpom.xmlにプラグインを利用する旨を宣言します。

<plugin>
  <groupId>com.github.github</groupId>
  <artifactId>site-maven-plugin</artifactId>
  <version>0.4</version>
  <configuration>
    <message>Building site for ${project.version}</message>
  </configuration>
  <executions>
    <execution>
      <goals>
        <goal>site</goal>
      </goals>
      <phase>site</phase>
    </execution>
  </executions>
</plugin>


 Next, open your '~/.m2/settings.xml' and create new <profile>. You have to write your GitHub's userName and password as plain text.
 次に'~/.m2/settings.xml'を開いて<profile>を新規に作成します。GitHubのユーザー名とパスワードを平文で記述する必要があります。

<settings>
  <profiles>
    <profile>
      <id>github-plugin</id>
      <activation>
        <activeByDefault>true</activeByDefault>
      </activation>
      <properties>
        <github.global.userName>your-name</github.global.userName>
        <github.global.password>your-password</github.global.password>
      </properties>
    </profile>
    ......
  </profiles>
  ......
</settings>

How to use

 What you need is just commanding `mvn site`. The gh-pages branch will be created at your remote repository. I recommend to add -Dgithub.site.dryRun to command line argument to test your setting at first.
 使い方はとても簡単、`mvn site`を叩くだけです。リモートリポジトリにgh-pagesブランチが作成されます。最初は-Dgithub.site.dryRunオプションを引数に追加して、設定がきちんとできていることを確認するといいでしょう。

 If your build fails, check that your pom.xml contains information of your repository like project.scm.developerConnection. Please read official document to know details of configurations.
 もしビルドが失敗するようなら、pom.xmlproject.scm.developerConnectionのようなリポジトリの情報が記述されているか確認してください。設定についての詳細は公式ドキュメントが頼りになります。


 This plugin doesn't support multi-module site, but very useful to host simple project. I used this plugin to host my maven-jsr305-plugin's site. Enjoy!
 どうやらマルチモジュールプロジェクトには対応していないようなのですが、シンプルなプロジェクトなら今の機能でも充分便利に使えるでしょう。私もmaven-jsr305-pluginのsiteを公開するのに使ってみました。皆さんもぜひお試しください。