将 Maven 站点发布到 GitHub Pages

本文源代码：https://github.com/chensoul/maven-site-github-example/ 。

创建 Java Maven 项目

让我们使用 Maven 创建一个简单的 Java 项目

mvn archetype:generate \
    -DgroupId=com.mycompany.app \
    -DartifactId=maven-site-github-example \
    -DarchetypeArtifactId=maven-archetype-quickstart \
    -DarchetypeVersion=1.4 \
    -DinteractiveMode=false

这将创建包含 Maven 项目的my-app文件夹。让我们进入该文件夹并确保它编译正常：

cd maven-site-github-example
mvn clean verify

我们还可以生成该项目的站点：

mvn clean site

该站点将在target/site文件夹中生成，可以使用浏览器打开；例如，让我们打开它的 index.html：

chrome target/site/index.html

maven-my-app-index

创建 github 项目

在你的 github 上创建一个项目 maven-site-github-example，然后在本地的 maven-site-github-example 目录提交代码：

echo "# maven-site-github-example" >> README.md
git init
git add .
git commit -m "first commit"
git branch -M main
git remote add origin git@github.com:chensoul/maven-site-github-example.git
git push -u origin main

GitHub Page 设置

现在我们必须在 Git 存储库上创建 gh-pages分支。

git checkout --orphan gh-pages
rm .git/index ; git clean -fdx
echo "It works" > index.html
git add . && git commit -m "initial site content" && git push origin gh-pages

相应的网站将发布在你的 GitHub 项目的相应 URL 中；访问地址：https://chensoul.github.io/maven-site-github-example：

maven-my-app-github-page-index

现在我们可以回到 主分支：

git checkout main

Maven POM 配置

让我们看看如何配置我们的 POM 以自动将 Maven 站点发布到 GitHub 页面。

在 pluginManagement 部分中添加 maven-scm-publish-plugin：

<build>
    <pluginManagement>
        <plugins>
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-scm-publish-plugin</artifactId>
                <version>3.0.0</version>
                <configuration>
                    <scmBranch>gh-pages</scmBranch>
                   <tryUpdate>true</tryUpdate>
                </configuration>
            </plugin>
        </plugins>
    </pluginManagement>
</build>

maven-scm-publish-plugin 插件需要以下参数，参考 https://maven.apache.org/plugins/maven-scm-publish-plugin/publish-scm-mojo.html：

从上面的参数说明，可以看出：

发布网站

在配置了 project.distributionManagement.site 之后，将 Maven 站点发布到 GitHub 页面只需运行以下命令：

mvn clean site scm-publish:publish-scm

从日志可以看出 git 推送提交的命令：'git' 'push' 'git@github.com:chensoul/maven-site-github-example.git' 'refs/heads/gh-pages:refs/heads/gh-pages'

[INFO] Executing: /bin/sh -c cd '/Users/chensoul/Codes/github/maven-site-github-example/target/scmpublish-checkout' && 'git' 'push' 'git@github.com:chensoul/maven-site-github-example.git' 'refs/heads/gh-pages:refs/heads/gh-pages'
[INFO] Working directory: /Users/chensoul/Codes/github/maven-site-github-example/target/scmpublish-checkout
[INFO] Checked in 24 file(s) to revision null in 0 h 0 m 4 s
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time:  21.115 s
[INFO] Finished at: 2024-07-18T10:25:58+08:00
[INFO] ------------------------------------------------------------------------

这里使用的是通过 ssh 协议提交，能够提交成功，是因为我已将本地的 ssh 公钥配置到 github。

现在该网站位于 GitHub Pages 上：

maven-my-app-github-index

如果不配置 project.distributionManagement.site ，注释 distributionManagement 节点，这需要配置 scmpublish.pubScmUrl，可以在 pom.xml 中设置：

<properties>
  <scmpublish.content>${project.reporting.outputDirectory}</scmpublish.content>
  <scmpublish.pubScmUrl>scm:git:git@github.com:chensoul/maven-site-github-example.git</scmpublish.pubScmUrl>
  <scmpublish.scm.branch>gh-pages</scmpublish.scm.branch>
</properties>


<!--    <distributionManagement>-->
<!--        <site>-->
<!--            <id>github</id>-->
<!--            <url>scm:git:git@github.com:chensoul/maven-site-github-example.git</url>-->
<!--        </site>-->
<!--    </distributionManagement>-->

再次运行：

mvn clean site scm-publish:publish-scm

美化网站

使用 maven-archetype-site 美化网站：

mvn archetype:generate \
    -DgroupId=com.mycompany.app \
    -DartifactId=maven-site-github-example \
    -DarchetypeGroupId=org.apache.maven.archetypes \
    -DarchetypeArtifactId=maven-archetype-site \
    -DarchetypeVersion=1.4 \
    -DinteractiveMode=false

执行成功之后，src 目录下新增了一个 site 目录，并且POM中添加了 maven-project-info-reports-plugin 和 i18n 本地化的一些配置。

<build>
    <pluginManagement>
        <plugins>
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-scm-publish-plugin</artifactId>
                <version>3.0.0</version>
                <configuration>
                    <scmBranch>gh-pages</scmBranch>
                </configuration>
            </plugin>
        </plugins>
    </pluginManagement>


    <plugins>
        <plugin>
            <artifactId>maven-site-plugin</artifactId>
            <configuration>
                <locales>en,fr</locales>
            </configuration>
        </plugin>
    </plugins>
</build>


<reporting>
    <plugins>
        <plugin>
            <artifactId>maven-project-info-reports-plugin</artifactId>
        </plugin>
    </plugins>
</reporting>

此外，最终网站将使用新皮肤 maven-fluido-skin。src/site/site.xml 内容如下：

<?xml version="1.0" encoding="UTF-8"?>


<project name="${artifactId}"
  xmlns="http://maven.apache.org/DECORATION/1.8.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://maven.apache.org/DECORATION/1.8.0 http://maven.apache.org/xsd/decoration-1.8.0.xsd">
  <bannerLeft>
    <name>${artifactId}</name>
    <src>https://maven.apache.org/images/apache-maven-project.webp</src>
    <href>https://www.apache.org/</href>
  </bannerLeft>


  <bannerRight>
    <src>https://maven.apache.org/images/maven-logo-black-on-white.webp</src>
    <href>https://maven.apache.org/</href>
  </bannerRight>


  <skin>
    <groupId>org.apache.maven.skins</groupId>
    <artifactId>maven-fluido-skin</artifactId>
    <version>1.7</version>
  </skin>


  <body>
    <links>
      <item name="Apache" href="http://www.apache.org/" />
      <item name="Maven" href="https://maven.apache.org/"/>
    </links>


    <menu name="Examples">
      <item name="APT Format" href="format.html"/>
      <item name="FAQ" href="faq.html"/>
      <item name="Markdown Example" href="markdown.html"/>
      <item name="Markdown with Velocity Example" href="markdown-velocity.html"/>
      <item name="Xdoc Example" href="xdoc.html"/>
    </menu>


    <menu ref="reports" />
  </body>
</project>

让我们再次运行以下命令来发布新网站：

mvn clean site scm-publish:publish-scm

稍等片刻，等待 github page 部署成功之后，可以看到网站：

maven-my-app-github-skin-index

可以在 https://github.com/chensoul/maven-site-github-example/actions 查看网站的部署：

maven-my-app-github-page-deploy

现在，可以通过添加/更改/删除目录 src/site 的内容，然后通过 Maven 再次发布该网站。

例如，删除 src/site/apt/index.apt，添加 src/site/apt/index.md.vm ，引入项目中 README.md 内容作为网站首页内容：

#include("/README.md")

Github Action配置

修改 Aciton 的 Workflow 权限，选中 Read and write permissions。

创建 .github/workflows 目录，并在该目录创建 site.yml：

name: Publish Site with Maven


on:
  push:
    branches: [ "main" ]
  pull_request:
    branches: [ "main" ]


jobs:
  build:
    runs-on: ubuntu-latest


    strategy:
      matrix:
        java: [ '8' ]


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


      - name: Java ${{ matrix.Java }}
        uses: actions/setup-java@v4
        with:
          distribution: 'temurin'
          java-version: ${{ matrix.java }}
          cache: maven
          server-id: github
          server-username: GITHUB_ACTOR
          server-password: GITHUB_TOKEN


      - name: Publish site to github pages
        run: |
          git config --global user.email "github-actions[bot]@users.noreply.github.com"
          git config --global user.name "github-actions[bot]"
          mvn -ntp -B -U clean site scm-publish:publish-scm -Dscmpublish.serverId=github
        env:
          GITHUB_ACTOR: ${{ secrets.GITHUB_ACTOR }}
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

在 github action 中，需要设置 github 的 username 和 password 用于提交代码带 gh-pages 分支，所以需要设置 scmpublish.serverId 并且删除 distributionManagement 下的 site 配置：

mvn --ntp --batch-mode --update-snapshots clean site scm-publish:publish-scm -Dscmpublish.serverId=github

server-id 相关信息可以在 actions/setup-java@v4 中设置，参考 actions/setup-java 的文档：

      - name: Java ${{ matrix.Java }}
        uses: actions/setup-java@v4
        with:
          distribution: 'temurin'
          java-version: ${{ matrix.java }}
          cache: maven
          server-id: github
          server-username: GITHUB_ACTOR
          server-password: GITHUB_TOKEN

另外，git 提交代码时，需要设置用户名和邮箱：

git config --global user.email "github-actions[bot]@users.noreply.github.com"
git config --global user.name "github-actions[bot]"

提交代码之后，Github Action 可以看到一个部署，稍等片刻，部署失败：

[INFO] --- maven-clean-plugin:2.5:clean (default-clean) @ maven-site-github-example ---
[INFO]
[INFO] --- maven-site-plugin:3.3:site (default-site) @ maven-site-github-example ---
Warning:  Report plugin org.apache.maven.plugins:maven-project-info-reports-plugin has an empty version.
Warning:
Warning:  It is highly recommended to fix these problems because they threaten the stability of your build.
Warning:
Warning:  For this reason, future Maven versions might no longer support building such malformed projects.
[INFO] configuring report plugin org.apache.maven.plugins:maven-project-info-reports-plugin:3.6.2
Warning:  Error injecting: org.apache.maven.report.projectinfo.CiManagementReport
java.lang.NoClassDefFoundError: org/apache/maven/doxia/siterenderer/DocumentContent

从日志可以看到 maven-clean-plugin 版本是 2.5，maven-site-plugin 版本是 3.3 ，maven-project-info-reports-plugin 版本是 3.6.2

修改 pom.xml ，给 maven-site-plugin 设置版本为 4.0.0-M15：

<plugin>
    <artifactId>maven-site-plugin</artifactId>
    <version>4.0.0-M15</version>
    <configuration>
        <locales>default,en,fr</locales>
    </configuration>
</plugin>

再次提交代码，发现 Github action 还是运行失败，异常日志：

[INFO] Executing: /bin/sh -c cd '/home/runner/work/maven-site-github-example/maven-site-github-example/target' && 'git' 'clone' '--branch' 'gh-pages' 'git@github.com:chensoul/maven-site-github-example.git' '/home/runner/work/maven-site-github-example/maven-site-github-example/target/scmpublish-checkout'
[INFO] Working directory: /home/runner/work/maven-site-github-example/maven-site-github-example/target
Error:  Failed to check out from SCM: The git-clone command failed. Cloning into '/home/runner/work/maven-site-github-example/maven-site-github-example/target/scmpublish-checkout'...
git@github.com: Permission denied (publickey).
fatal: Could not read from remote repository.


Please make sure you have the correct access rights
and the repository exists.

从日志可以看到 git 从 git@github.com:chensoul/maven-site-github-example.git下载代码，没有权限，原因是没有配置 ssh。故需要修改 scmpublish.pubScmUrl 为 https 协议，将 <scmpublish.pubScmUrl>scm:git:git@github.com:chensoul/maven-site-github-example.git</scmpublish.pubScmUrl>改为：

<scmpublish.pubScmUrl>scm:git:https://github.com/chensoul/maven-site-github-example.git</scmpublish.pubScmUrl>

再次提交代码，action 运行成功。

再次打开网站，发现存在 I18N 没有替换成功的问题。

maven-my-app-github-i18n-index

解决办法：

再次发布并打开网站，则正常显示：

maven-my-app-github-i18n-index-ok

GitLab Runner安装和部署
Git使用