GitHub Actions 作为静态生成器和 GitHub Pages 上的站点的 CI/CD

稍微浏览了一下 Habr 后，我很惊讶地发现关于 GitHub（测试版）功能 Actions 的主题发表的文章很少。

这种轻描淡写的说法似乎可以用以下事实来解释：该功能仍在测试中，尽管是“测试版”。但这是测试版的一个有用功能，允许在私有存储库中使用该工具。我将在本文中讨论如何使用这项技术。

史前

如果我们按顺序开始，那么可能值得一提的是，在寻找一种快速、方便、简单且免费的存储个人“关于我”网站的选项的过程中，我不得不花费几个晚上并梳理许多文章。

有些人选择托管，另一些人选择云服务器，而那些不想了解所有这些工作、交互和付款的人，例如将静态站点上传到存储库，因为现在这可以在 GitHub 和 GitLab 上完成。

当然，这是每个人的个人选择。

我最终的选择是 GitHub Pages。

关于页面

谁不知道 gh-pages - 这是一个以网站形式存储文档的选项，它是免费提供的，除了文档之外，还建议存储个人网站。此功能由 GitHub 向所有用户提供，并可在存储库设置中使用。

项目存储库使用分支 gh-pages，对于用户站点 - 具有名称的单独存储库 username.github.io 网站来源位于 master 分支。

你可以看到更多在文档中，但我要指出的是，GitHub 出人意料地慷慨，允许任何人通过简单地添加文件来将自己的域链接到这样的网站 CNAME 使用域名并在 GitHub 服务器上设置域名提供商的 DNS。

我确信这里有很多关于如何开发这样一个网站的文章，所以这不是我要进一步讨论的内容。

问题的发生

问题是，当使用静态生成器时，需要编写额外的脚本并使用库来简化生成页面并将其加载到存储库中的过程。简单来说，如果将源存储在单独的私有存储库中，那么每次站点有任何更改时，都需要部署本地环境，以便后续生成静态页面并在主站点存储库中发布。

有丰富的静电发生器他们都有同样的问题。这些操作需要花费太多的时间和精力，最终会减慢站点的工作速度，特别是在多次从操作系统迁移到操作系统或发生硬盘数据丢失事件之后 （我的情况就是这样）.

就在最近，无论是在网站上的弹出通知中还是在 GitHub 的新闻通讯中，都注意到了一个新构建的 CI/CD，它允许以最小的努力执行这些操作。

关于静态页面生成器

我不会特别关注这个分项，但我会分享我在选择和使用以下内容时得出的一些论点：

1）选择一款适合你的编程语言的生成器，或者尽可能清晰的生成器。当我自己必须为网站添加一些功能以使其正常运行时，我想到了这个想法，并添加拐杖以提高其稳定性和自动化程度。此外，这是您自己以插件的形式编写附加功能的一个很好的理由；

2）选择哪个生成器是个人选择，但值得考虑的是，为了最初沉浸在 GitHub Pages 功能的工作中，您必须首先安装杰奇。幸运的是，它允许您直接从存储库中的源生成网站 （我会根据我的选择重复这一点）.

我对生成器的选择是基于第一点。鹈用Python编写的很容易取代Jekyll，这对我来说很陌生 （用了快一年了）。因此，即使是创建和编辑文章以及在网站上工作，也能以我感兴趣的语言获得额外的经验。

制定问题

主要任务是编写一个脚本（实际上是一个配置文件），该脚本将自动从私有存储库生成静态页面。该解决方案将涉及虚拟环境的功能。该脚本本身会将现成的页面添加到公共存储库中。

解决方案工具

我们将用来解决问题的工具：

GitHub 操作；
蟒蛇3.7；
鹈;
吉特；
GitHub 页面。

该解决方案

因此，在稍微熟悉了文档并了解了 Actions 脚本是如何编写的之后，很明显这种机制将彻底解决所出现的问题。 在撰写本文时，您必须订阅才能使用此功能。 用于 Beta 测试!

GitHub Actions 作为静态生成器和 GitHub Pages 上的站点的 CI/CD
Github 本身对新功能的描述

编写操作脚本首先在文件夹中创建命名文件 .github 及其子文件夹 workflows。这可以手动完成，也可以通过存储库页面上“操作”选项卡中的编辑器完成。

GitHub Actions 作为静态生成器和 GitHub Pages 上的站点的 CI/CD
空白脚本表单示例

我将简要评论表格

name: CI    # название скрипта: будет отображаться во вкладке Actions

on: [push]  # действие, по которому запускается данный скрипт

jobs:       # роботы, которые будут выполняться
  build:    # сборка, которая..

    runs-on: ubuntu-latest      # ..будет запущена на основе этого образа

    steps:              # шаги которые будут проделаны после запуска образа
    - uses: actions/checkout@v1     # переход в самую актуальную ветку
    - name: Run a one-line script   # имя работы номер 1
      run: echo Hello, world!       # суть работы номер 1 (bash-команда записана в одну строку)
    - name: Run a multi-line script   # имя работы номер 2
      run: |                    # суть работы номер 2 (многострочная)
        echo Add other actions to build,
        echo test, and deploy your project.

让我们根据模板编写自己的：

0) 您也可以保留名称“CI”。这是一个品味问题。

1) 接下来，您需要选择将启动脚本的操作/触发器，在我们的例子中，这是通常将新提交推送到存储库的操作。

on:
  push

2）脚本运行所依据的图像也将从示例中保留，因为 Ubuntu 就所需功能而言，它相当令人满意。可用工具很明显，这可以是任何必要的或简单方便的映像（或基于它的 Docker 容器）。

  build:
    runs-on: ubuntu-latest

3）步骤中，我们首先要搭建好环境，为主要工作做准备。

3.1）转到我们需要的分支（标准步骤 checkout):

- uses: actions/checkout@v1

3.2）安装Python：

    - name: Set up Python
      uses: actions/setup-python@v1
      with:
        python-version: 3.7

3.3）安装我们的生成器的依赖项：

    - name: Install dependencies
      run: |
          python -m pip install --upgrade pip
          pip install -r requirements.txt

3.4) 创建一个将生成网站页面的目录：

   - name: Make output folder
      run: mkdir output

4）为了使站点上的工作保持一致，即不删除以前的更改并能够将更改添加到站点存储库而不发生冲突，下一步将是每次克隆站点存储库：

   - name: Clone master branch
      run: git clone "https://${{ secrets.ACCESS_TOKEN }}@github.com/${GITHUB_ACTOR}/${GITHUB_ACTOR}.github.io.git" --branch master --single-branch ./output

这一步调用系统变量：

变量 GITHUB_ACTOR GitHub 会自行安装，这是启动此脚本的用户名；
变量 secrets.ACCESS_TOKEN 这是生成的用于管理 Github 的令牌，我们可以通过在选项卡中设置它来将其作为环境变量传递 Secrets 我们的存储库设置。 请注意，在生成过程中，令牌将提供给我们一次，之后将无法进一步访问它。以及Secrets物品的价值。

5）让我们继续生成页面：

   - name: Generate static pages
      run: pelican content -o output -s publishconf.py

传递给生成器的参数负责生成的文件将发送到的目录（-o output）和我们用来生成的配置文件（-s publishconf.py; 您可以在 Pelican 文档中了解分离本地配置和发布配置的方法).

让我提醒您一下我们的文件夹中有什么 output 站点存储库已被克隆。

6) 让我们设置 git 并索引我们更改的文件：

    - name: Set git config and add changes
      run: |
          git config --global user.email "${GITHUB_ACTOR}@https://users.noreply.github.com/"
          git config --global user.name "${GITHUB_ACTOR}"
          git add --all
      working-directory: ./output

此时，将使用已知的变量，并指示将在其中启动此步骤的命令的工作目录。否则，转到工作目录的命令将类似于 - cd output.

7) 让我们生成一条提交消息，提交更改并将其推送到存储库中。这样提交就不会白费，因此不会在 bash 中产生错误（输出结果不是 0）——首先，让我们检查是否有必要提交和推送某些内容。为此，我们使用命令 git diff-index --quiet --cached HEAD -- 这将输出到终端 0 如果相对于网站的先前版本没有任何更改，并且 1 有这样的变化。然后我们处理该命令的结果。因此，在有关脚本执行的信息中，我们将记录有关此阶段站点状态的有用信息，而不是自动崩溃并向我们发送有关脚本崩溃的报告。

我们还在我们的目录中使用现成的页面执行这些操作。

   - name: Push and send notification
      run: |
          COMMIT_MESSAGE="Update pages on $(date +'%Y-%m-%d %H:%M:%S')"
          git diff-index --quiet --cached HEAD -- && echo "No changes!" && exit 0 || echo $COMMIT_MESSAGE
          # Only if repo have changes
          git commit -m "${COMMIT_MESSAGE}"
          git push https://${{ secrets.ACCESS_TOKEN }}@github.com/${GITHUB_ACTOR}/${GITHUB_ACTOR}.github.io.git master
      working-directory: ./output

导致

因此，这样的脚本可以让你不用考虑创建静态页面。通过直接将更改添加到私有存储库，无论是在任何系统下使用 git 还是通过 GitHub Web 界面创建文件，Actions 都会自行完成所有操作。 如果脚本意外崩溃，则会向您的电子邮件发送通知。

完整代码

我将保留我的工作版本，其中最后一步添加发送提交已推送到主存储库的通知。

使用上述 Secrets，其中添加机器人令牌和需要向其发送消息的用户 ID。

name: Push content to the user's GitHub pages repository

on:
  push

jobs:
  build:
    runs-on: ubuntu-latest

    steps:
    - uses: actions/checkout@v1
    - name: Set up Python
      uses: actions/setup-python@v1
      with:
        python-version: 3.7
    - name: Install dependencies
      run: |
          python -m pip install --upgrade pip
          pip install -r requirements.txt
    - name: Make output folder
      run: mkdir output
    - name: Clone master branch
      run: git clone "https://${{ secrets.ACCESS_TOKEN }}@github.com/${GITHUB_ACTOR}/${GITHUB_ACTOR}.github.io.git" --branch master --single-branch ./output
    - name: Generate static pages
      run: pelican content -o output -s publishconf.py
    - name: Set git config and add changes
      run: |
          git config --global user.email "${GITHUB_ACTOR}@https://users.noreply.github.com/"
          git config --global user.name "${GITHUB_ACTOR}"
          git add --all
      working-directory: ./output
    - name: Push and send notification
      run: |
          COMMIT_MESSAGE="Update pages on $(date +'%Y-%m-%d %H:%M:%S')"
          git diff-index --quiet --cached HEAD -- && echo "No changes!" && exit 0 || echo $COMMIT_MESSAGE
          git commit -m "${COMMIT_MESSAGE}"
          git push https://${{ secrets.ACCESS_TOKEN }}@github.com/${GITHUB_ACTOR}/${GITHUB_ACTOR}.github.io.git master
          curl "https://api.telegram.org/bot${{ secrets.BOT_TOKEN }}/sendMessage?text=$COMMIT_MESSAGE %0ALook at ${GITHUB_ACTOR}.github.io %0ARepository%3A github.com/${GITHUB_ACTOR}/${GITHUB_ACTOR}.github.io&chat_id=${{ secrets.ADMIN_ID }}"
      working-directory: ./output

屏幕截图

GitHub Actions 作为静态生成器和 GitHub Pages 上的站点的 CI/CD
源存储库的“操作”选项卡中显示的其中一项运行的结果

GitHub Actions 作为静态生成器和 GitHub Pages 上的站点的 CI/CD
来自机器人的有关脚本完成的消息

有用的链接

了解行动
动作语法
触发器列表
虚拟环境选项
Github页面
静态生成器列表

来源： habr.com