Github Actions 学习指南

全篇共 4090 字。按500字/分钟阅读,预计用时 8.2 分钟。总访问 80 次,日访问 3 次。

基于持续继承和持续开发的软件开发的最佳实践,GitHub 推出 Actions 功能。监听围绕代码仓库管理的各种事件,比如 push 和 pull_request 事件,触发提前计划好的一系列步骤,即工作流。这些步骤用 YAML 文档记录。触发工作流包括了构建和测试。这些工作流可以在 GitHub 的服务器上执行,开发者也可以在自己的服务器响应从GitHub触发的事件来执行工作流。

持续集成与持续开发

CI,全称是 Continuous Intergratiion,意思是持续集成。CD,全称是 Continuous Development,意思是持续开发。它们是一种软件开发与构建部署的最佳实践,或者称作一种行为指导或思考方式。它鼓励团队成员频繁地向代码仓库提交代码,这通常意味着能更快的检测出软件和代码中存在的错误,减少开发人员在查找产生错误的源头时需要检索的代码量。

这就像吃自助餐,为了减少粮食的浪费,餐厅建议顾客“多次少取”。就好比我们每餐吃的事物,听谁说建议“多餐少吃”,每一餐适可而止。每次向代码仓库提交少量代码,且这些代码只做一件事,明确每次提交的意图,并鼓励多次提交。但这种进餐方式并不适合所有人,比如没有一天除了三餐没有其他时间进餐的工作者。就像 CI/CD 并不适合所有软件项目。

每一次将代码提交到代码仓库,就可以使用 GitHub Actions 构建和测试一次代码,以检测每一次提交是否引入错误,并立即修复错误。这些自动化的测试工作包括:代码格式化、安全检查、代码覆盖率、功能测试以及其他自定义检查。

构建和测试代码,肯定需要在一台计算机上执行。过去我们在本地构建和测试代码,现在你可以把这些操作交给 GitHub Actions 完成,这也是它的意义所在。你有两套方案,一套是在 GitHub 为你提供的机器上构建和测试你提交的代码,另一套就是在自己的服务器上。无论用那种方案,你都需要告诉 GitHub Actions 该怎么做,所以你需要编写一个配置文件,来告诉 GitHub Actions 何时、何地、如何构建和测试你提交的代码。

YAML 基础用法

GitHub 要求使用 YAML 来配置你的工作流。配置文件的文件名必须以 .yml.yaml 为扩展后缀。所以要想把 GitHub Actions 用起来,必须学会如何使用 YAML 语法是毋庸置疑的。这是 YAML 的官方网站。如果你和现在的我一样,是 YAML 的初学者,没有精力阅读它的完整语法,你可以看看这篇 《5分钟学会 YAML》。然后再阅读这篇 《Workflow syntax for GitHub Actions》,就足够你把 GitHub Actions 用起来了。

在 YAML 文档中到处都能看到键值对(Key-Value),简写是 KV。YAML 是 JSON 的超集,就像 Typescript 是 JavaScript 的超集一样。你如何在 JSON 中表示数组、对象,就可以如何在 YAML 中使用它们。

Name: Value
a_json_style_map: {"K": "V"}
a_json_style_sequence: ["pink", "red", "red", "cat", 123, 234, 345]

使用空格缩进,不要使用 Tab 缩进。键值对之间也要用空格分隔。下面两个键值对,第二个是错误的写法,因为冒号后面必须紧跟一个空格。这就是规则。

# 正确
Key: Value

# 错误,冒号后面用空格间隔
Key:Value

告诉 YAML 文档从哪里开始,从哪里结束。YAML 文档开始于 ---,结束于 ...。你也可以不告诉 YAML 文档的开始和结束位置,因为这是可选的。如果行首是 # ,那么这一行就是注释,就像 HTML 文档用 <!-- --> 作注释,JavaScript 中用 // 作单行注释一样。每个语言都有自己的注释规则。

下面是几种简单的键值对用法。你会发现比 JSON 更自由更灵活,怪不得说 YAML 是 JSON 的超集。Key 和字符串的 Value 可以不用双引号包括。而且还能包含空格,就像写句子一样。

key: value
someNumber: 299
quotedText: "some text description"
moreQuotedtext: strings do not have to be quoted, but I prefer to do it=
boolean: true
we can also have spaces in keys: and also in values
nullKeyValue: null

集合和列表。如果你用过 Markdown,它也是基于空格控制格式的,而且 - 符号在 Markdown 中也是代表一个列表项。

# a collection of fancy cars
Fancy-Cars
  - Porsche
  - Aston Martin
  - Bentley

了解更多高级 YAML 语法用法,从上面的 YAML 官方网站里面查询吧。

配置工作流

工作流(Workflow)就是一系列自动化的步骤。这些步骤描述用 YAML 文档记录,YAML 文档存储在 .github/workflow/ 目录中,.github/ 目录必须在仓库的根目录中。

何时触发执行这些工作流的动作呢?这里就要提到事件监听。就像我们经常用 JavaScript 编写监听用户各种鼠标点击事件一样。YAML 文档中也记录了当发生什么事件时触发执行工作流的动作。对 GitHub Actions 来说,push、pull request 等等就是事件。我们可以规定当这些或某一个事件发生时执行某个动作。

学会了 YAML 的基础语法,然后看 YAML 具体是如何在 GitHub Actions 配置文件中使用的,这篇 《Workflow syntax for GitHub Actions》 就是在讲这个。

下面是一段非常简单的用 YAML 语言编写的工作流配置代码。name 值就是工作流的名字。代码仓库的 .github/workflow/ 目录下的每个 YAML 文档描述一个工作流。我创建了两个 YAML 文档,所以这里显示有两个工作流。

name:     
on: push
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
    - name: Checkout
      uses: actions/checkout@v2.0.0
    - name: list all
      run: ls -la
    - name: pwd
      run: pwd

jobs 下可包含多个作业,上面只有一个名为 build 的作业。运行环境指定为 ubuntu-latest。这个作业包含三个步骤,第一步是引入官方的 action:action/checkout@v2.0.0,它的作用是把项目代码下载到当前目录下,可以使用 with 指令设定选项,比如只下载某个分支等。第二步我想输出目录内的文件结构。第三步我想输出当前目录的绝对路径。

我觉得比较有意思的事件是 schedule。它就像定时任务,在规定的时间点触发工作流。这篇 《scheduled-events-schedule》 详细介绍如何写一个定时任务。

下面是每 15 分钟执行一次工作流的事件触发记录。每一条记录都包括:触发该工作流的事件(这里是通过 schedule 事件触发的)、由谁触发的(airglass 是我的 GitHub 账号),哪一次提交,还有执行工作流耗时多久,完成工作流的时间等信息。

GitHub Actions 学习指南

使用限制

没有规矩,不成方圆。既然使用 GitHub Actions,就要遵守它的规则。我把使用限制总结为两个主要方面。第一是用法限制。第二是用量限制。用法限制,就是限制你使用它的目的必须不能触碰法律、道德和 GitHub 社区行为规范。用量限制,就是指对时间、空间的限制,比如限制接口调用次数,限制任务执行时长,限制任务数等。

这些规则可能会在未来发生变动,所以我不在这里赘述,附上原网址对这部分的说明:Usage limits

结语

因为这只是一篇关于 GitHub Actions 的学习指南,用我的亲身体验记录我学习 GitHub Actions 的过程,所以本篇不会出现具体的示例项目。如果我以后想到了比较有趣的应用 GitHub Actions 的场景,我会重新写一篇文章,记录这个项目的详细实现过程。