GitHub Actions 之自动化发布 Maven 项目

news2025/2/28 15:39:14

开发开源数据中台项目 datacap 时，之前发布版本都是通过在本地编译并部署到 maven 中央仓库中，这样就导致是非自动化工程，于是通过搜索发现 samuelmeuli/action-maven-publish 这个 github 自动化工具可以帮助我们来做这些事情，本文主要详细讲解如何通过它进行自动化发布 maven 项目到 maven 中央仓库中。

必要条件

已经获得发布到中央仓库中的授权
在 github 代码仓库中包含授权的仓库
OSSRH 相关的账号和密码
GPG 签名

修改项目 pom 文件支持发布到中央仓库

假设我们已经在 github 中已经包含仓库，我们需要修改项目的 pom.xml 文件来支持发布，需要添加以下依赖：

<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-source-plugin</artifactId>
    <version>${plugin.maven.source.version}</version>
    <executions>
        <execution>
            <phase>package</phase>
            <goals>
                <goal>jar-no-fork</goal>
            </goals>
        </execution>
    </executions>
</plugin>

使用 maven-source-plugin 可以帮助确保项目的源代码能够方便地被其他人获取和使用，从而促进了项目的协作和可维护性。发布到中央仓库中也是需要对 source 做一些检查，如果没有将无法进行发布成功。

<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-javadoc-plugin</artifactId>
    <version>${plugin.maven.javadoc.version}</version>
    <executions>
        <execution>
            <phase>package</phase>
            <goals>
                <goal>jar</goal>
            </goals>
        </execution>
    </executions>
    <configuration>
        <tags>
            <tag>
                <name>Description</name>
                <placement>test</placement>
                <head>description</head>
            </tag>
        </tags>
        <additionalOptions>-Xdoclint:none</additionalOptions>
        <failOnError>false</failOnError>
    </configuration>
</plugin>

使用 maven-javadoc-plugin 可以帮助确保项目的 API 文档能够方便地被其他人获取和使用，发布到中央仓库中也是需要对文档做一些检查，如果没有将无法进行发布成功。

<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-gpg-plugin</artifactId>
    <version>${plugin.maven.gpg.version}</version>
    <executions>
        <execution>
            <phase>verify</phase>
            <goals>
                <goal>sign</goal>
            </goals>
            <configuration>
                <!-- Prevent `gpg` from using pinentry programs -->
                <gpgArguments>
                    <arg>--pinentry-mode</arg>
                    <arg>loopback</arg>
                </gpgArguments>
            </configuration>
        </execution>
    </executions>
</plugin>

使用 maven-gpg-plugin 可以提高项目的安全性和可信度，特别是在开源项目中，数字签名可以帮助用户验证下载的文件是否经过篡改。这一点尤为重要，每次的发布是签名是必须要通过的。

⚠️ 需要注意的是：在使用自动化工具的时候一定要配置

<configuration>
    <!-- Prevent `gpg` from using pinentry programs -->
    <gpgArguments>
        <arg>--pinentry-mode</arg>
        <arg>loopback</arg>
    </gpgArguments>
</configuration>

这样的话自动化工具才可以跳过手动输入签名密码的步骤，方便签名成功

<plugin>
    <groupId>org.sonatype.plugins</groupId>
    <artifactId>nexus-staging-maven-plugin</artifactId>
    <version>${plugin.maven.nexus.version}</version>
    <extensions>true</extensions>
    <configuration>
        <serverId>ossrh</serverId>
        <nexusUrl>https://s01.oss.sonatype.org/</nexusUrl>
        <autoReleaseAfterClose>true</autoReleaseAfterClose>
    </configuration>
</plugin>

使用 nexus-staging-maven-plugin 可以帮助你更轻松地管理 Maven 项目的发布，确保项目的发布过程正确、可靠、安全。通过它可以将项目自动化发布到中央仓库。

配置 GPG 签名信息

以下操作需要保证本地已经存在 gpg 签名

通过使用以下命令进行信息获取：

gpg --list-secret-keys

获取成功后返回类似如下代码：

[keyboxd]
---------
sec   ed25519 2023-10-15 [SC]
      E20C364D039BF231FC03BD30AFC85804B60F7E64
uid             [ 绝对 ] qianmoq (Devlive Software Foundation) <shicheng@devlive.org>
ssb   cv25519 2023-10-15 [E]

代码中的 E20C364D039BF231FC03BD30AFC85804B60F7E64 就是我们需要到的签名的 Key

然后通过该 Key 获取私钥，使用以下代码获取：

gpg -a --export-secret-keys E20C364D039BF231FC03BD30AFC85804B60F7E64

执行命令后会返回类似如下内容：

-----BEGIN PGP PRIVATE KEY BLOCK-----

lIYEZS***
=9lTo
-----END PGP PRIVATE KEY BLOCK-----

我们需要将返回的所有内容复制下来需要用到。

在 github 中配置项目信息

我们打开 github 项目，比如我们使用的是 datacap

点击顶部的 Settings 菜单，将会跳转到以下页面

接下来我们点击 Secrets and variables 菜单下的 Actions 进入配置页面

点击 New repository secret 分别添加以下 4 个配置：

GPG_SECRET
GPG_PASSWORD
OSSRH_USERNAME
OSSRH_TOKEN

GPG_SECRET 中添加签名获取到的私钥，也就是 gpg -a --export-secret-keys E20C364D039BF231FC03BD30AFC85804B60F7E64 返回的结果

GPG_PASSWORD 输入 GPG 签名的密码（这个是在生成 GPG 签名填写的密码）

OSSRH_USERNAME 输入在 OSSRH 中的用户名

OSSRH_TOKEN 输入在 OSSRH 中的密码

编写发布 maven 自动化脚本

通过以上配置完成后，我们使用以下代码可以实现自动化发布项目的 maven 中央仓库

name: Publish via Maven Central

on:
  release:
    types: [ published ]

jobs:
  publish-maven-central:
    runs-on: ubuntu-latest
    steps:
      - name: Check out Git repository
        uses: actions/checkout@v4

      - name: Install Java and Maven
        uses: actions/setup-java@v3
        with:
          java-version: '11'
          distribution: 'temurin'

      - name: Publish to the Maven Central Repository
        uses: samuelmeuli/action-maven-publish@v1
        with:
          maven_profiles: 'deploy'
          maven_goals_phases: 'clean deploy'
          maven_args: '-DskipTests'
          gpg_private_key: ${{ secrets.GPG_SECRET }}
          gpg_passphrase: ${{ secrets.GPG_PASSWORD }}
          nexus_username: ${{ secrets.OSSRH_USERNAME }}
          nexus_password: ${{ secrets.OSSRH_TOKEN }}