iT邦幫忙

2021 iThome 鐵人賽

DAY 13
0
DevOps

不僅是程式碼代管平台 - Github 能做些什麼?系列 第 13

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。

https://ithelp.ithome.com.tw/upload/images/20210912/20091494yZUSjtDaAE.png


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 如下表
https://ithelp.ithome.com.tw/upload/images/20210912/20091494rsxAbAljHp.png

若你想要知道每一個 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)
│ │ │ │ │                                   
│ │ │ │ │
│ │ │ │ │
* * * * *

特別符號所代表意義如下:
https://ithelp.ithome.com.tw/upload/images/20210912/20091494zQxNU41wSp.png


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

https://ithelp.ithome.com.tw/upload/images/20210912/20091494Rz1WqJDkPw.png


閱讀完這篇文章,你應該對於 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


上一篇
GitHub Action YAML - 語意解析與指令說明
下一篇
GitHub Action YAML 撰寫技巧 - 環境變數(Environment Variables) 與 秘密 (Secrets)
系列文
不僅是程式碼代管平台 - Github 能做些什麼?30

尚未有邦友留言

立即登入留言