该材料对于初学者以及希望通过内置GitHub工具快速提高乳胶CI / CD的人很有用。
介绍
前几天，我用CV来浏览存储库（幸运的是，我使用乳胶制作了模板），我认为最好将某种类型的单一位置组织在文档的当前版本始终所在的位置。
基本要求很简单：
- 以最小的努力来发布该站点；
- 自动更新网站上的内容。
我想到了一个管道形式的解决方案：
- 将提交推送到GitHub;
- 在CI / CD中构建.tex文件；
- 将收集的pdf提交到GitHub版本;
- 在名片站点上更新pdf文件。
在本文中，我们将仔细研究每个步骤。该站点将是GitHub Pages。对于CI / CD，我们将使用GitHub Actions。
我们需要：
- GitHub帐户；
- LaTeX编译工具；
- 任何文本编辑器（我使用的是为Latex配置的VIM ）；
走！
连接GitHub动作
在这里，可以从站点执行所有操作，而无需诉诸控制台。
转到“操作”（红色下划线）。
并在此处找到“简单工作流程”卡，然后按“设置此工作流程”按钮
具有工作流程模板的编辑器将在我们之前打开。值得更详细地讨论这一点。
GitHub Actions与Workflows一起使用，在单独的文件中进行描述。每个工作流程包括：
- 名称（部分
name: …）； - 启动条件（部分
on: …）； - 要执行的任务清单（部分
jobs: …）
每个作业还包含称为step的较小块。每个步骤都是一个原子动作（一次完成）。在这种情况下，step具有其自己的名称（
name: …）和命令列表（run: …），并且还可以使用第三方开发人员提供的现成操作（uses: …）。
第三方动作是GitHub Actions中最强大的部分。他们可以做很多事情：安装JDK，在tox中运行python测试等等。在本教程中，我们将使用xu-cheng / latex-action @ v2编译乳胶（西里尔文没有问题），并且actions / upload-artifact @ v2来上传工件。
让我们回到编辑器。可以更正建议的模板，将其显示为以下形式：
name: Build and deploy latex sources to GitHub Pages
on: push
jobs:
build:
# , . ubuntu
runs-on: ubuntu-latest
steps:
# action,
- uses: actions/checkout@v2
#
- name: Build document
uses: xu-cheng/latex-action@v2
with:
# ,
root_file: main.tex
# .
working_directory: latex_sources/
# , (latexmk)
# -jobname=<name>
args: -jobname=my_doc -pdf -file-line-error -halt-on-error -interaction=nonstopmode
compiler: latexmk
# pdf-
- name: Upload pdf document
uses: actions/upload-artifact@v2
with:
#
name: my_doc
# pdf. «*», «**»
# <working_directory>/<jobname>.pdf
path: latex_sources/my_doc.pdf
将其保存到文件中，为文件选择任何名称（可以使用latex.yml）。在将文件的创建提交给Web编辑器之后，第一个构建应该转到GitHub Actions，结果将出现工件-编译的pdf。
万岁！现在您可以开始发布了。
设置自动发布
GitHub中的发布系统具有一个特殊性：发布始终与带有标签的提交相关。因此，我们有两个选择：
- 将标记手动添加到我们要收集和发布pdf文件的提交中；
- 自动标记所有提交并释放它们。
对我来说，第二种选择似乎更方便。我通常会在工作完成时（逻辑上或今天）提交并推送。因此，将来我将谈论他。
要创建发行版，我们将使用action / create-release @ v1动作，并将pdf文件上传到创建的发行版（是的，它是单独上传的），我们将使用actions / upload-release-asset @ v1。
让我们添加一个新工作：
deploy:
runs-on: ubuntu-latest
# master. ,
if: github.ref == 'refs/heads/master'
# job. .
needs: [build]
steps:
# , bash-
- name: Variables
# id : step
id: vars
# echo ${{ steps.<step_id>.outputs.<variable_name> }}
# | — yaml. ,
run: |
echo «::set-output name=date::$(date +'%Y-%m-%d')»
echo «::set-output name=sha8::$(echo ${GITHUB_SHA} | cut -c1-8)»
- name: Download artifacts
uses: actions/download-artifact@v2
with:
# , upload-artifact
name: my_doc
- name: Create Release
uses: actions/create-release@v1
id: create_release
env:
# ., GITHUB_TOKEN
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} # This token is provided by Actions
with:
# step id=vars (. ).
# “my_doc-< >-< 8 sha >
tag_name: my_doc-${{ steps.vars.outputs.date }}-${{ steps.vars.outputs.sha8 }}
# ,
release_name: My Actions document (version ${{ steps.vars.outputs.date }})
# , false
draft: false
prerelease: false
# step
- name: Upload pdf asset
uses: actions/upload-release-asset@v1
env:
#
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
with:
# step id=create_release upload_url —
upload_url: ${{ steps.create_release.outputs.upload_url }}
# latex_sources, download-artifacts
asset_path: ./my_doc.pdf
# ,
asset_name: my_asset_name.pdf
asset_content_type: application/pdf
添加到工作流文件中，提交更改。转到“操作”，然后看到又增加了一个步骤：
同时，编译的pdf也出现在发行版中。
剩下的唯一事情就是将其上传到站点。
调出GitHub Pages
GitHub为每个项目提供创建网页的功能，并为其提供免费托管。但是您不必了解JS / CSS / HTML就能编写出值得的东西！开箱即用的服务提供了一些漂亮的模板，可以完全解决布局问题。您所需要做的就是填写Markdown文档，其余的工作由系统完成。
我们转到存储库的“设置”部分，然后在“选项”选项卡（默认情况下首先打开）中向下滚动至“ GitHub页面”。
在这里，我们选择master分支作为源，并选择/ docs作为文件夹（您也可以使用/ root，但我希望在项目根目录中保留最少数量的文件）。点击“保存”。
“主题选择器”按钮将打开模板库，在其中可以通过单击绿色的“选择主题”按钮来对模板进行戳戳，查看和选择。
选择一个主题之后，我们将被扔到Web编辑器中，在该编辑器中建议编辑Markdown文件，该文件随后将成为站点。在这里，您可以描述自己内心渴望的一切：从简单的自我介绍到文档的目标和作品的功能。
对内容满意后，提交更改。
我的页面在哪里？
组合页面的链接始终存储在“设置”->“ GitHub页面”中。最好在资源库的网站上注册它（主页上“关于”字段旁边的齿轮），以免丢失它。
下载最新版本
有一个小技巧：始终可以通过将URL中的commit标记替换为“ latest”来引用最新版本及其所有文件。在我们的示例中，要从最新版本获取my_asset_name.pdf文件，我们需要插入一个link
https://github.com/<your_username>/<repo_name>/releases/latest/download/my_asset_name.pdf。
就我而言，是：https : //github.com/alekseik1/github_actions_latex_template/releases/latest/download/my_asset_name.pdf。
完成这些步骤后，GitHub Pages始终链接到最新版本。
结果
我们将GitHub Actions设置为自动构建pdf文件，将其发布，然后在GitHub Pages上建立一个包含最新版本的网站。该项目的最终版本可以在这里找到。
感谢您的关注！