使用 Github Actions 自动化编译、发布 LaTeX 文档

Github Actions 是 Github 推出的持续化集成工具，进一步加快软件开发的编译、部署、发布流程基于 Github 进行多人协作编辑 Latex 文档是非常先进的科研文档写作方式，如今可以利用 Github Actions 进一步完善协作流程。

主要功能与优势Latex 文档的编译由 Github Actions 所提供的虚拟容器环境所支持，无需协作者本地配置环境，降低编译环境差异带来的歧义 Github Actions 体现了先进的 CI/CD 理念，配合 Github Pages 可以持续迭代发布论文版本，允许协作者在线查看文档。

Github Actions 具备丰富的自动化能力，可以满足协作者的特殊喜好，如可以同时发布“单栏”、“双栏”两种格式的 PDF 文档，协作者可以根据不同场景选择阅读不同样式的文件 Github Actions 还允许作者自动发布 release 版本，在论文写作到达里程碑时，协作者可以轻松地为当前版本 PDF 文档加标签并发布出去。

…预备知识 https://docs.github.com/en/actions/quickstart：阅读 Quickstart 文档了解 Github Actions 的基本信息，学会如何创建一个 Github Actions 配置文件并对其进行更新。

https://docs.github.com/en/pages/quickstart：阅读 Quickstart 文档了解 Github Pages 的基本信息，学会如何为论文项目仓库开启 Github Pages 功能。

git 相关内容：commit, branch, tag, gitignore…动手实践 如果你不需要对本文提供的自动化流程做任何修改，可以跳过这部分经过前面的了解，我们知道使用 Github Actions 非常简单，只需要完成一个配置文件的编写即可，在这里我已经写好了一个功能还算强大的配置文件，对应的参考项目为：。

https://github.com/RavenLite/LatexActions其中该 Action 分为基本的“Latex 编译”和多种形式的“PDF 发布”两个环节，可根据不同的使用习惯和安全考虑

选择不同的“PDF 发布”方式name: Build and Release LaTeX document on: push: branches: [ main ] tags: – v* pull_request: branches: [ main ] workflow_dispatch: jobs: build_release_latex: runs-on: ubuntu-latest steps: – uses: actions/checkout@v2 – name: Compile LaTeX document uses: xu-cheng/latex-action@v2 with: root_file: main.tex – name: Stash PDF run: | mv main.pdf $HOME # cache the file – name: Create Branch uses: peterjgrainger/action-create-branch@v2.0.1 env: GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} with: branch: gh_actions_builds – name: Checkout gh_actions_builds Branch uses: actions/checkout@v1 with: ref: gh_actions_builds – name: Commit PDF run: | git config –local user.email “raven.xu98@gmail.com” git config –local user.name “Raven Xu” mv $HOME/main.pdf $(pwd) # bring it back git add -f main.pdf git commit -m “Updated by GitHub Action Automatically” – name: Push PDF uses: ad-m/github-push-action@v0.5.0 with: branch: gh_actions_builds force: false github_token: ${{ secrets.GITHUB_TOKEN }} – name: Release uses: softprops/action-gh-release@v1 if: startsWith(github.ref, refs/tags/) with: files: main.pdf env: GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}。

Step 1 – Compile LaTeX document：编译 Latex 文档 Step 2 – Stash PDF：缓存编译后生成的 PDF 文件 Step 3 – Create Branch：创建一个专门的分支用于管理 PDF 文件

Step 4 – Checkout gh_actions_builds Branch：切换到我们上一步创建的分支 Step 5 – Commit PDF：提交 PDF 至当前分支 Step 6 – Push PDF：提交更新到仓库

Step 7 – Release：根据版本号发布新版本进一步说明Github Actions 执行成功后我们可以在如下几个网站看到生成的 PDF 文件 gh_actions_builds 分支里，如此处：

https://github.com/RavenLite/LatexActions/blob/gh_actions_builds/main.pdfGithub Pages 里，如此处：https://ravenxu.top/LatexAction

s/main.pdfReleases 里，如此处：https://github.com/RavenLite/LatexActions/releases要特别说明的是，第一种和第三种方式因为是在 Github 的仓库内查看，所以只有有该仓库可读权限的人才能访问。

但是第二种方式没有权限控制，任何得到该链接的人都可以访问 因此，如果你编译的是未公开发表的论文，一般不建议你使用该种方式预览 PDF 文件所幸，第二种方式是默认禁用的，只有当你在仓库的“Settings-Pages”中开启了 Github Pages，才会被发布到公开链接上。

2. 为了让 Releases 的版本更有意义，只有当使用 git 提交了 tag 的时候，发布 Release 的作业才会被触发 （tag 的命名需要满足 v* 的格式，如 v1.0，v2.1.3-basic。

提交 tag 的参考命令如下）git tag git push origin 3. 示例配置文件中的 Latex 文件名为 main.tex，你可以根据自己的需要进行替换，注意替换对应的 PDF 文件名。

4. 请将第五步中的邮箱地址和名字替换为你的信息。