@action/checkout 如何抓取所有的历史记录

2021年1月29日 ~ 白宦成 ~ Leave a comment

GitHub 的 Action Template 中默认带了一个 checkout 插件，这个插件可以实现将你的项目 Clone 到 CI 的运行环境中，从而执行各项操作。

为了提升速度，Github 在实际上实现的时候，默认会限制 depth=1，这就导致在 clone 的时候，仅 clone 一个 commit ，如果你需要依赖 git 进行操作，则需要更多的 commit 。

在具体的实现过程中，你需要做的仅仅是在配置 github action 中的 fetch-depth 选项，设置为你需要的 commit 数量。如果你需要的是所有的 commit，则将该选项设置为 0。具体配置如下

- uses: actions/checkout@v2
        with:
          fetch-depth: 0

这样你就可以在 CI 中访问到所有的数据。

不过，这样你并不能直接执行诸如 git merge-base 这样的命令，因为你虽然将所有的数据抓取到了本地，但并没有建立相应的分支，则需要你先建立相应的分支，才能进行处理。

这个时候你可以在 action 当中新增一行，用来切换分支。

- run: git checkout x

这里的 x 是你需要操作的分支，不过你需要注意，切换过来以后，还需要重新切换回去，不然你的代码就版本不对了。

如何使用 GitHub Action 自动部署 MKDocs

2021年1月29日 ~ 白宦成 ~ Leave a comment

MKDocs 是一个基于 Python 写成的文档生成工具，在实际的使用过程中，我们可以借助 GitHub Action 来实现自动部署到 GitHub Pages 。

操作流程

首先，你需要先在本地生成一个 MKDocs 项目

生成后，你可以在项目的根目录创建 GitHub Action 所需目录。

mkdir -p .github/workflows/

并创建一个配置文件 publish_docs.yml

name: Publish docs via GitHub Pages
on:
  push:
    branches:
      - main
jobs:
  build:
    name: Deploy docs
    runs-on: ubuntu-latest
    steps:
      - name: Checkout main
        uses: actions/checkout@v2
      - name: Deploy docs
        uses: mhausenblas/mkdocs-deploy-gh-pages@master
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          CONFIG_FILE: mkdocs.yml
          EXTRA_PACKAGES: build-base

创建完成后，将配置文件添加到版本控制中，并提交到 GitHub 上，就可以在你提交代码的时候，自动推送到 GitHub Pages 中。

需要注意的是，我使用的是 MKDocs 的 Material Design 主题，如果你使用的是其他主题（非自带的主题），则需要修改 EXTRA_PACKAGES 的配置。

代码解读

这个配置文件中主要是 on 和 steps 比较有学习的价值。

on:
  push:
    branches:
      - main

这段代码限制了，只有在 main 分支上，出现了 commit 的时候，才会触发这个 action 的执行，如果是其他的分支，则不会触发 action 的构建。

    steps:
      - name: Checkout main
        uses: actions/checkout@v2
      - name: Deploy docs
        uses: mhausenblas/mkdocs-deploy-gh-pages@master
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          CONFIG_FILE: mkdocs.yml
          EXTRA_PACKAGES: build-base

这里的两个 step，第一个是 clone 出所有的代码, 第二个 step 就是我使用一个已经做好的 action mhausenblas/mkdocs-deploy-gh-pages@master,这个 action 的作用就是将 mkdocs 的文档生成并部署到 GitHub Pages 中。

这个 action 自带了 material design 的主题，执行后，会构建并推送到 GitHub Pages。如果你使用的也是这个主题就可以直接按照我的样式进行配置。如果你使用的不是这个主题，则需要将你的主题配置在 EXTRA_PACKAGES，从而让 action 在执行的时候安装相应的 package。

总结

GitHub Action 的 Marketplace 中有大量的现成 Action 可以供你使用，借助现成的 Action ，你可以非常简单的完成自己的 CI/CD 流程，非常方便。

LCTT 从Travis CI迁移到 GitHub Action 实践

2021年1月16日 ~ 白宦成 ~ Leave a comment

LCTT 的 CI 已经在 Travis CI 上运转了多年，一致保持着良好的使用体验。自 2019 年 Github 推出了自家的 CI 工具 Github Action 后，我们就在考虑将 CI 从 Travis-CI 迁移到 Github，以降低维护和沟通的成本，并借助于 GitHub Action Marketplace 实现更强的功能。

最近，因为 TravisCI 屡屡部署出错，而我们的账户因为使用的较多，已经超出了免费使用的限制，以此为契机，将 CI 从 Travis CI 迁移到 GitHub Action。

项目介绍

Translate Project 是 LCTT 翻译组的主要协作项目，几百位译者通过 GitHub 进行围绕开源、Linux、软件工程等领域的文章翻译，从 2013 年来，累计了大量的 Commit，致使项目下有非常多的文件。

Transalte Project 借助于 CI 帮助译者进行基本的文章格式进行检查；并定时执行命令，以进行所有的文章检查，对于超时未完成翻译的工作进行回收；对于文章的状态进行标记，生成相应的 Badge。

迁移思路

Travis CI 和 Github Action 在使用方面，其实总体差异不会太大，都是基于 YAML 文件格式来编写配置文件。不过，和 Travis CI 不同的是，Github Action 支持多个不同的配置文件，因此，你可以根据不同的场景，设定不同的配置文件，降低单个配置的文件的复杂度。

此外，由于我们的脚本中依赖了一些 Travis CI 的环境变量，也需要将其替换为 Github Action 中的相应环境变量，从而确保脚本可以运转。

改造实践

1. 分析之前的 CI 流程

我们在 TravisCI 上的 CI 配置文件如图

总体可以分为三块：

命令区：说明了安装阶段和执行阶段的操作有哪些
条件区：指定了这个配置文件在哪些条件下会生效
部署区：写明了构建产物如何进行部署

在命令区中，有预置的安装过程和后续的执行过程。在安装过程中，安装了一些依赖，并将当前的 pages 资源克隆到本地，以继承上一次构建生成的资料。

在条件区则指明了仅作用于 master 分支

在部署区便是将前面命令区的执行结果进行部署。

在实际的执行过程中，还会根据环境变量不同，决定是否要执行特定的命令，这部分在后续的改造过程中，就可以调整部署，拆分到不同的文件中。

2. 直译配置文件

在完成了基本的分析后，就可以建立新的 Action 配置文件了。由于基本的语法很类似，对于其中的不少内容可以进行直译。

比如，我们的配置文件在直译后，结果如下

直译的文件已经可以直接运行，不过，这里有很多不满足需要的地方，所以需要做一些修改。

3. 恢复 Travis CI 的环境变量

由于我们使用的 Badge 等生成脚本并非我所编写，所以在这一次的迁移中，并不打算对齐进行调整，以避免出现故障。而脚本中依赖了一些变量，需要将其重新设置出来。

Github Action 提供了一些方法，可以让你手动设置环境变量。你可以在你的构建的 step 中，加入如下代码，从而在构建环境中设定 TRAVIS_BRANCH 和 TRAVIS_EVENT_TYPE 环境变量，确保你可以使用这个环境变量。

 - <strong>name</strong>: Set ENV variables
        run: |
          echo "::set-env name=TRAVIS_BRANCH::${TRAVIS_BRANCH:-$(echo $GITHUB_REF | awk 'BEGIN { FS = "/" } ; { print $3 }')}"
          echo "::set-env name=TRAVIS_EVENT_TYPE::$(if [ "schedule" == "$" ]; then echo "cron"; else echo "$"; fi)"

Code language: JavaScript (javascript)

此外，由于 set-env 这个方法相对比较危险，你还需要在环境变量中，开启危险函数的执行。

jobs:
  build:
    runs-on: ubuntu-latest
    env:
      ACTIONS_ALLOW_UNSECURE_COMMANDS: true

Code language: JavaScript (javascript)

4. 拆分配置文件

Github Action 和 TravisCI 不同的一点是你可以将你的 CI文件拆分成多个文件，从而降低每一个单独的配置文件的复杂度。

根据前面对于流程的分析，可以将我们的 CI 流程拆分成三个部分：

生成 badge 文件，应当跟随每一次 commit 进行
生成 status 文件，执行时间较长，可以定期执行
根据 Pull Request 内容进行整理，做核验

则将我们的配置文件拆分成三个不同的文件

LCTT 从Travis CI迁移到 GitHub Action 实践 - 15

也得益于拆分开，则在 checker 中就可以免于安装一些必要的依赖，从而精简 CI 流程，提升 CI 的执行时间。

5. 测试 CI 的运行情况

在完成了配置文件的编写和拆分后，就可以进行本地的执行测试。Github Action 写完了，难免要执行一下，确保整个流程是正常的。

这个时候你可以安装工具（https://github.com/nektos/act），来在本地执行 action ，从而确认你的代码执行是正确的。

如果你是 macOS ，只需要执行 brew install act 就可以安装 act 工具，来完成 act 的安装。

安装完成 act ，就可以通过执行 act 命令来在本地执行 action ，比如，执行 act pull_request来触发 GitHub 的 Pull Request 事件

通过本地测试后，再将你的配置文件推送到 GitHub 上，进行生产环境的测试即可。

6. 移除 Travis-CI

通过上述的一些步骤，我们完成了从 Travis CI 到 GitHub Action 的迁移，此时，就可以移除项目根目录中的 .travis.yml 文件，彻底关闭 travis-ci。

7. 修改 GitHub 的 Branch 保护条件

为了确保修改符合标准，我们限制了新的 Pull Request 必须通过 CI 检查，才能合并进入 master，因此，也需要修改相应的分支保护规则，确保设定相应的保护。

一些注意事项

1. 环境变量不同

如果你依赖了环境变量，则需要进行相应的修改。或者可以像我一样，先通过 set-env 来让本地拥有临时的环境变量，后续再逐步进行迁移。

2. Action 运行依赖要注意安全

Action 执行过程中会有两个部分。action 本身流程依赖于 master，但执行过程中调用的脚本是根据 source 决定的，因此，从安全角度来看，你应当尽可能将所有的流程放在 Action 中，而不是放在你的源码目录中。

总结

通过对 TravisCI 的流程整理、代码修改等流程，我们将之前的 Travis-CI 迁移至速度更快、性能更好的 GitHub Action ，一方面可以优化我们的工作流，另一方面，也让我们的代码更加简洁明了。

对于还在使用 Travis CI 的项目来说，也可以考虑迁移到 GitHub Action 中，来优化自己的工作流。

参考阅读

https://mauricius.dev/run-and-debug-github-actions-locally/
https://jeffrafter.com/working-with-github-actions/
https://developer.okta.com/blog/2020/05/18/travis-ci-to-github-actions

被 GitHub Action 坑了半天…

2021年1月12日 ~ 白宦成 ~ Leave a comment

我这几天在忙着搞 LCTT 的 Travis-CI 迁移到 Github Action 。整体的 CI 的流程都已经迁移完成了，但是一个特定的检查脚本死活无法正常运行。

在这个过程中我尝试了多种办法，比如修改代码、调整里面的参数、打印其中的参数，似乎都是工作运行正常的。

将项目代码 clone 到本地后，发现代码在本地运转也是正常的。

我一直不知道问题出在哪里，百思不得其解。直到我在跑了几百次 Action 构建后，我发现，Github 默认的 checkout 插件是有问题的。

和标准的 git clone 不同， Github 默认的 Checkout 插件在实际 clone 项目是使用的不是 git clone 命令，而是采用先在本地 init 一个目录，并添加相应的 remote ，并 fetch 代码下来。

这样的好处是在处理的时候，只会 fetch 到特定的分支到本地，而不会将默认的其他分支一同 clone
到本地。但坏处就是你在执行的时候，只能针对特定的分支进行操作。

而检查脚本则是基于 git 本身的命令进行执行的，因此是需要比如 master 这样的分支的，这就导致在使用了默认的 checkout 插件的时候，检查脚本无法使用。

与之对比的，是 Travis CI 在执行 Clone 的时候，采用的是全量 Clone ，再单独 Fetch 某个特定分支。从这个角度上来看，我可以理解 Github Action 为什么会 Clone 的更快一些。不过，这种 Clone 的方式确实给一些 CI 在 Check 时留下隐患。

总结

如果你在 Github 中使用默认的 Checkout 插件获取项目以后，执行 Git 操作出现了问题，很有可能是插件自己的问题，而不是你的问题。你可以选择自己构建 clone 命令，避免这个问题。