GitHub Actionsを使ってMaven Centralにライブラリをデプロイする

GitHub ActionsからMaven Centralへライブラリをリリースする

前回の記事では、Mavenを使って手動でライブラリを公開する方法をまとめました。

しかし、実際の運用では、ローカル環境から mvn deploy するのではなく、CI/CD基盤を使って自動化するのが一般的です。本記事では、「GitHub Actions」 を利用して、タグのプッシュをトリガーに Maven Central へのリリースと、GitHub Pages へのドキュメント公開を自動化する方法を解説します。

前提条件

• Mavenでライブラリをビルドできること
• Maven Centralへの認証情報を取得済みであること
• GPG署名の準備ができていること
• 詳細は前回の記事を参照してください。

Javaライブラリリリースgithub actionファイル

次のようなYAMLファイルを.github/workflowsに配置します。

タグ v* が push された場合、もしくはGitHubの画面から手動実行した場合（workflow_dispatch）に起動し、ライブラリをビルドし、パブリッシュします。

name: Publish to Maven Central & GitHub Pages

on:
  workflow_dispatch:
  push:
    tags:
      - "v*"

jobs:
  publish:
    runs-on: ubuntu-latest
    permissions:
      contents: read

    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Set up Java and Maven
        uses: actions/setup-java@v5
        with:
          distribution: temurin
          java-version: "21"
          cache: maven
          server-id: central
          server-username: MAVEN_CENTRAL_USERNAME
          server-password: MAVEN_CENTRAL_PASSWORD
          gpg-private-key: ${{ secrets.GPG_PRIVATE_KEY }}
          gpg-passphrase: MAVEN_GPG_PASSPHRASE

      - name: Build and publish
        run: mvn -B -ntp clean deploy
        env:
          MAVEN_CENTRAL_USERNAME: ${{ secrets.MAVEN_CENTRAL_USERNAME }}
          MAVEN_CENTRAL_PASSWORD: ${{ secrets.MAVEN_CENTRAL_PASSWORD }}
          MAVEN_GPG_PASSPHRASE: ${{ secrets.GPG_PASSPHRASE }}

主な設定項目について解説します。

Set up Java and Maven

- name: Set up Java and Maven
  uses: actions/setup-java@v5
  with:
    distribution: temurin
    java-version: "21"
    cache: maven
    server-id: central
    server-username: MAVEN_CENTRAL_USERNAME
    server-password: MAVEN_CENTRAL_PASSWORD
    gpg-private-key: ${{ secrets.GPG_PRIVATE_KEY }}
    gpg-passphrase: MAVEN_GPG_PASSPHRASE

actions/setup-java@v5を使っています。
これはJavaを使うワークフローでよく使われますが、実はmavenのsettings.xmlを生成する機能も持っています。

以下のように設定値を設定します

項目	説明
distribution、java-version	ビルドに使うJavaバージョンを指定します。
cache	キャッシュ用の設定です。maven、gradle、sbtを指定できます。
server-id	pom.xml の publishingServerId と一致させる必要があります。
server-username	ユーザー名が格納されている環境変数名を指定します。
server-password	パスワードが格納されている環境変数名を指定します。
gpg-private-key	GPG秘密鍵を直接渡します（BEGIN PGP PRIVATE KEY BLOCK を含む文字列）。gpg --export-secret-keys --armorで取得できる文字列です。
gpg-passphrase	パスフレーズが格納されている環境変数名を指定します。

server-username などに直接 secrets.XXX を書くのではなく、あくまで「環境変数名」を指定する点に注意してください。実際の値は mvn コマンド実行時の env セクションで渡します。

シークレットの指定

リポジトリの上部のsettingsタブ→Secrets and variables（/settings/secrets/actions）のページから設定できます。
Repository secretsで設定しました。
ここのNew Repository secretで設定したNameを使ってワークフローからsecrets.GPG_PRIVATE_KEYのようにしてシークレット情報を利用できます。

Build and publish

mvn -B -ntp clean deployコマンドを実行してパブリッシュします。

以下のような環境変数を設定します。
この環境変数名はactions/setup-javaに設定したものとあっている必要があります（setup-javaでserver-usernameをデフォルトのGITHUB_ACTORとしている場合は例で使っているMAVEN_CENTRAL_USERNAMEでなくGITHUB_ACTORという環境変数を用意してください）

• MAVEN_CENTRAL_USERNAME、MAVEN_CENTRAL_PASSWORD
  • maven centralへログインするのに必要な情報です。Maven Centralのページで取得できます（参考）
• MAVEN_GPG_PASSPHRASE
  • GPG 鍵のパスフレーズです

補足（javadocとjacocoをgithub pagesで公開する）

以上でライブラリをリリースすることはできるようになります。ついでに Javadoc と jacoco のレポートを github pagesで公開する方法も紹介します。

javadoc HTMLファイルの生成

まずpom.xmlの設定が必要です。
特に設定を加えなくてもmvn siteを実行するとtarget/site/にライブラリのメタデータをまとめたHTMLが生成されます。
しかし、これにはjavadocが含まれません。

そこで以下のような設定を加えます。

<project>
  ...
  <reporting>
    <plugins>
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-javadoc-plugin</artifactId>
        <version>3.6.3</version>
      </plugin>
    </plugins>
    ...
  </reporting>
  ...
</project>

デフォルト設定で動作しますが、詳細は公式ドキュメントを参照してください。

この設定を追加した後mvn siteを実行し、target/site/index.htmlを開くとjavadocページも追加されています。
少しわかりにくいですが、左のメニューのProject Reportsからjavadocページへ遷移できます。

jacoco HTMLファイルの生成

jacocoはカバレッジを測定するためのライブラリで、HTMLでカバレッジに関するレポートを生成することもできます。
まずmavenを使ってjacocoでHTMLレポートを生成する設定を加えます。

以下のようにpom.xmlにjacocoの設定を追加してください（junitに関する設定はできているものとします）

<project>
  ...
  <build>
    <plugins>
      <plugin>
        <groupId>
          org.jacoco
        </groupId>
        <artifactId>
          jacoco-maven-plugin
        </artifactId>
        <version>
          0.8.12
        </version>
        <executions>
          <execution>
            <id>
              prepare-agent
            </id>
            <goals>
              <goal>
                prepare-agent
              </goal>
            </goals>
          </execution>
          <execution>
            <id>
              report
            </id>
            <goals>
              <goal>
                report
              </goal>
            </goals>
          </execution>
        </executions>
      </plugin>
    </plugins>
  </build>

  ...

  <reporting>
    <plugins>
      <plugin>
        <groupId>
          org.jacoco
        </groupId>
        <artifactId>
          jacoco-maven-plugin
        </artifactId>
        <reportSets>
          <reportSet>
            <reports>
              <!-- select non-aggregate reports -->
              <report>
                report
              </report>
            </reports>
          </reportSet>
        </reportSets>
      </plugin>
    </plugins>
  </reporting>
  ...
</project>

これで

mvn test jacoco:report

を実行するとtarget/site/jacoco/index.htmlにレポートが生成されるはずです。

さらに上記のようにreportingにもjacocoの設定があると

mvn test site

でHTMLを生成し、target/site/index.htmlを開くと javadoc のページと同様の場所に jacoco のレポートもできています。

参考

github pagesにデプロイする

ワークフローYAML

ここまでで公開したいHTMLファイルは生成できるようになりました。次はgithub pagesにデプロイできるようにするためにGitHub Actionsのワークフローを修正します。
以下のような記述をYAMLに追加します。

  build-site:
    needs: publish
    runs-on: ubuntu-latest

    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Set up Java and Maven
        uses: actions/setup-java@v5
        with:
          distribution: temurin
          java-version: "21"
          cache: maven

      - name: Build site
        run: mvn -B -ntp clean test site

      - name: Upload GitHub Pages artifact
        uses: actions/upload-pages-artifact@v4
        with:
          path: target/site

  deploy-site:
    needs: build-site
    runs-on: ubuntu-latest
    permissions:
      pages: write
      id-token: write

    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}

    steps:
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v4

この設定でtarget/siteに生成されたHTMLをgithub pagesにデプロイできるようになります。

GitHubの設定を変更

Build and deployment

ただし、デフォルトのリポジトリ設定だと、エラーになります。

まず、GitHub pagesをactionからデプロイできるようにします。
settingsタブのPagesページ（/settings/pages）からBuild and deploymentのSourceをGitHub Actionsに変更します。

これでgithub actionsからデプロイできるようになります。

Environments

もし「特定のタグがプッシュされた時」にactionsが起動する場合はさらに設定の追加が必要です。

同じくsettingsタブからEnvironmentsへ遷移してgithub-pagesのprotection ruleを変更します。

Deployment branches and tagsは当初はmainブランチへのプッシュでのみ起動するようになっているはずです。

これに「Add deployment branch or tag rule」から「Ref type:Tag」を選択しv*などのように入力し、タグのプッシュでもgithub pagesのデプロイが可能なように変更します。
これでタグプッシュでライブラリリリースとgithub pages公開が同時に進むようになります。

参考リポジトリ

本稿の内容は次のリポジトリで試しました。

なお、javadocなどは次のURLにあります。

ライブラリは次のURLで確認できます