雖然在前幾篇文章，我們有解釋 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