自动部署Javadoc到Github Pages

需求

由于想开一个新坑,打算把项目通过Maven生成的的Javadoc使用 Github Actions 自动部署到同项目下 gh-pages 分支,作为该项目 Github Pages 的主页供其他人参考。

操作

1. 配置 Maven 生成JavaDoc

首先在项目的 pom.xml 中添加 Maven Javadoc Plugin ,依赖这个插件,我们可以自动生成JavaDoc。

设置过后,我们就可以输入 mvn javadoc:javadoc 命令生成该项目的Javadoc了,生成的路径一般在 target/site/apidoc/ 下。

如果是使用的 mvn package 命令,则会生成在 target/apidoc/ 下。

2. 配置Github项目的Deploy KeysSecrets

因为我们需要把Javadoc放到同项目下的gh-pages分支,因此在Actions中需要进行认证操作,才可以正常推送。

这里我们打算采用SSH进行推送,并通过 Deploy Keys 进行认证。

a. 生成 OpenSSH 密钥

我们可以访问 Generate SSH Keys Online 在线生成一个密钥。

generate key

点击后,在下方会生成对应的私钥(Private Key)与公钥(Public Key),我们先记下。

b. 添加私钥到 Secrets

复制上一步得到的私钥,添加到项目的Secrets中。

add secret

名字(Name)填DEPLOY_PRI,数值(Value)填私钥内容

confirm secret

c. 添加公钥到 Deploy Keys

复制之前得到的公钥,添加到项目的Deploy Keys中。

add deploy key

名字(Title)可以随便填,我这里选择的是JAVADOC_DEPLOY,密钥(Key)填公钥内容。注意一定要勾选 “Allow write access“, 这样才可以被用于推送。

confirm deploy key

3. 配置 Github Actions

在项目下新建 .github/workflows/javadoc.yml 文件。这个文件会被自动识别为Github Actions配置文件。

记得也要在Settings中启用 Github Actions ,否则无法使用哦。

内容如下

随后,推送项目,在Actions界面找到该配置,手动触发一次。

run-action

等待其正常跑完,即可发现多了一个 gh-pages 分支。

4. 设置 Github Pages

在项目的Settings界面找到 Pages 一栏,选择 gh-pages 分支,点击 Save ,等待片刻即可访问 <用户名>.github.io/<项目名> 看到项目的Javadoc了。

Setting Pages.png

参考文献