GitHub Action YAML - 语意解析与指令说明

GitHub Action 的 workflow 是以 YAML 档案进行设定 (副档名为 .yml 或 .yaml)。YAML 是一种 data serialisation 语言，可读性高。YAML 以换行符号与缩排方式进行语法区隔，但相当严谨，多余的空白或 Tab 是不被允许的。以上一篇使用的 simple workflow 为例，它的 YAML 档案长相如下(我们翻译/修改了部分注解为中文，让您比较好阅读)：

# workflow 名称
name: CI

# 什麽情况下触发 workflow
on:
  # 对於 main branch 建立 Branch 与 Pull Request 时触发 workflow 
  push:
    branches: [ main ]
  pull_request:
    branches: [ main ]

  # 允许你从 Action 页签上手动执行 workflow
  workflow_dispatch:

# Job 可以循序或平行执行
jobs:
  # 这个 workflow 只有一个 job，名称为 "build"
  build:
    # 这个 job 会执行在作业系统为 ubuntu 的 runner
    runs-on: ubuntu-latest

    # 作为 Job 的一部分，Steps 会循序执行一连串的动作
    steps:
      # 在 $GITHUB_WORKSPACE 下签出您的存储库，以便您的工作可以访问它
      - uses: actions/checkout@v2

      # 在 Runner 上使用 shell 显示出 Hello world
      - name: Run a one-line script
        run: echo Hello, world!

      # 执行一组的指令
      - name: Run a multi-line script
        run: |
          echo Add other actions to build,
          echo test, and deploy your project.

接下来，我们会对常见的语意进行说明：

name

Workflow 名称，也是在 Action 操作页面中，工作流程清单的显示名称；倘若没有设定名称，则会以 workflow 文件路径+档案名称命名，如下图所示：

on

必填，触发在 workflow 的 Event 名称。可以以单一 Event 字串、Event 阵列、事件类型阵列 或 event configuration map 进行设定

job

预设情况下是平行(并行)执行，你可以使用 jobs.<job_id>.needs 来设定每个 Job 相依性，进而设定循序执行

step

Job 包含一系列的 Step，以循序方式执行命令、设定工作与 action。step 内不一定只能执行 action，但 action要作为 step 执行。每个步骤皆在 Runner 上执行，可以存取资料区与文件系统。

uses

选择要执行的 Action

Action 是可以重复使用的程序码单元(Unit of Code)，可以透过 JavaScript 或 Docker Container 方式撰写，并发布至 marketplace 提供其他人使用。您可以使用已经定义好的 Action (放置於 workflow 相同的 Repo、public repo 或已经发布的 Docker Continer Registry) 来进行重复的工作 (如：签出储存库)

Action 的名称格式相当重要，官方也建议在使用上指定版本(Git Ref, SHA, 或 Docker Tag)，确保使用正确的 Action，也不会因为发布者更新版本而导致 workflow 中断。其格式如下：
{owner}/{repo}@{ref}

范例如下
actions/heroku@main

看完上面密密麻麻的注解与语意说明，开始觉得头痛了吗? 别着急，YAML 档案本身可读性很高，只要了解每个语意代表的意思，静下心读完，你即可发现这个 workflow 其实在：

当 Main branch 发生建立 Branch/Pull request，会触发 CI workflow，将储存库的内容签出，并且列印出下列文字

Hello, world!
Add other actions to build,
test, and deploy your project.

而这个 Workflow 执行在 ubuntu 的 runner，允许手动执行；执行内容有一个 Job，依序执行 3 个 Step：

1. 签出 Repo 内容 (使用 actions/checkout@v2 这个 action)
2. 印出文字
3. 印出文字

阅读完本篇文章，相信你已经拥有阅读 YAML 且大致理解 workflow 想要做什麽事情的基本能力。若有遇到不能理解的语法，可以参考本篇文章最下面的参考资料(GitHub Docs)，也能快速融会贯通其功能。在下一篇文章，我们会针对 Event 做更详细的介绍。

若喜欢我的文章，欢迎点 like、分享与订阅，谢谢

参考资料

https://docs.github.com/en/actions/reference/workflow-syntax-for-github-actions
https://docs.github.com/en/actions/creating-actions/about-actions