GitHub Event - 触发 workflow 重要设定

虽然在前几篇文章，我们有解释 GitHub Action workflow 内的 Event 是什麽，但可能对於这个触发功能能做到甚麽程度可能只有基本的认识。在 GitHub 官方文件中，对於 GitHub Event 的定义为: 您可以在 GitHub 上发生特定活动时、特定时间 或 GitHub 外部发生事件时触发 workflow。这表示 GitHub Action 除了透过 GitHub 上的操作行为(如：Create Issue 或 Create Pull Request) 触发 workflow 外，也能透过排程与 外部呼叫 Github API 触发 workflow。

Event

若有阅读过上一篇 GitHub Action YAML - 语意解析与指令说明 的读者应该不陌生，在 YAML 内我们使用 on: 来定义触发的条件，其单一行为触发语法如下:

// 当建立 pull request 时触发 workflow
on: pull_request

如果多种行为进行触发的语法如下：

// 当推送程序码或建立 pull request 时触发 workflow
on: [push, pull_request]

理所当然，你可以多个行为排列组合进行触发，语法范例如下：

// 只有在 Main Branch，当推送程序码或建立 pull request 时触发 workflow
on:
  push:
    branches:
      - main
  pull_request:
    branches:
      - main

你还可以定义更细的行为，举个例子：在 Main Branch 且 opened/Assigned Pull Request 这两个行为的时候，才进行触发，语法如下：

on:
  pull_request:
    types: [assigned, opened]
    branches:
      - main    

对於 GitHub Webhook Event:
Pull Request 为 Webhook event payload
assigned 为 Activity types

相信对於读者来说，理解这些内容不难。比较麻烦的部分在於：如何知道有哪些 Webhook event payload 与 Activity types 可以使用？ 以 Pull Request 为例，他的 Activity types 如下表

若你想要知道每一个 Webhook event 怎麽使用，可以参考：
GitHub Webhook event

Schedule

Schedule 是在指定的时间(周期)触发 workflow。GitHub Event 的排程设定采用的是 cron syntax，主要执行 Default 或 Base Branch 上最新的 commit，而最短的执行周期为 5 分钟。

若你要在 UTC 时间 13:30 执行 workflow，其范例语法如下

on:
  schedule:
    # * 在 YAML 档案中是关键字，所以必须用 ' ' 包起来
    - cron:  '30 13 * * *'

Cron Syntax 表示方式如下

┌───────────── minute (0 - 59)
│ ┌───────────── hour (0 - 23)
│ │ ┌───────────── day of the month (1 - 31)
│ │ │ ┌───────────── month (1 - 12 or JAN-DEC)
│ │ │ │ ┌───────────── day of the week (0 - 6 or SUN-SAT)
│ │ │ │ │                                   
│ │ │ │ │
│ │ │ │ │
* * * * *

特别符号所代表意义如下：

repository dispatch

倘若你想要透过外部方式触发 workflow，你可以采用 repository dispatch 方式进行。他是采用 GitHub RestAPI方式进行触发。在使用 repository dispatch 触发 workflow 之前，你必须

1. 在 YAML 档案内加上 repository_dispatch，范例语法如下：

on:
  repository_dispatch:
    types: [opened, deleted]

注意：repository_dispatch 没有 Activity types，但是你必须自定 Types 让 Client 以带参数的方式呼叫 API

API 的格式如下：
URL [POST] /repos/{owner}/{repo}/dispatches

阅读完这篇文章，你应该对於 GitHub Event 以及如何触发 workflow 有深度的了解。在下一篇文章，我们要稍微深入一点讨论 YAML： 环境变数(Environment Variables) 与 秘密(Secrets)。

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

参考资料:

https://docs.github.com/en/actions/reference/events-that-trigger-workflows
https://docs.github.com/en/rest/reference/repos#create-a-repository-dispatch-event