github 的 actions 要如何被觸發?

2026-03-20

GitHub Actions 的觸發機制非常靈活，主要是透過在工作流程文件（YAML）中的 on 關鍵字來定義。你可以把它想像成一個「監聽器」，當特定事件發生時，它就會啟動自動化程序。

以下是常見的三大觸發類別：

1. 事件觸發（Event-driven）

這是最常用的方式，當 GitHub 儲存庫（Repository）發生特定動作時觸發。

push: 當代碼被推送到特定分支時觸發。
pull_request: 當 PR 被建立、更新或關閉時觸發。
issues: 當有人建立、編輯或回應 Issue 時觸發。
release: 當你發布新的版本（Release）時觸發。

YAML

on:
  push:
    branches: [ "main" ]
  pull_request:
    branches: [ "main" ]

2. 排程觸發（Scheduled）

如果你需要定期執行任務（例如：每天凌晨備份資料庫、每週掃描漏洞），可以使用 Unix 的 Cron 語法。

schedule: 設定特定的時間點執行。

YAML

on:
  schedule:
    # 格式：分 時 日 月 週 (這裡代表每天凌晨 0 點)
    - cron: '0 0 * * *'

3. 手動與外部觸發（Manual / External）

有時候你可能只想在需要時點一下按鈕，或者由另一個系統來叫醒它。

workflow_dispatch: 在 GitHub 介面上手動點擊「Run workflow」按鈕。你甚至可以設定輸入參數（Inputs）。
repository_dispatch: 透過 GitHub API 從外部系統（如：你的伺服器、Slack）觸發。
workflow_run: 當另一個工作流程（Workflow）完成後，自動接著執行這一個。

常見觸發條件過濾器

為了精確控制，你可以加上過濾條件，避免不必要的執行浪費額度：

過濾器	說明	範例
`branches`	只針對特定分支	`branches: [ main, dev ]`
`paths`	只有特定路徑的檔案變動才觸發	`paths: [ 'src/**' ]`
`tags`	只有推送到符合格式的標籤時觸發	`tags: [ 'v*' ]`
`types`	針對事件的細項動作	`types: [ opened, reopened ]`

💡 小提醒：

預設情況下，GitHub Actions 只會讀取 預設分支（通常是 main） 上的 .github/workflows/ 資料夾中的 YAML 檔案。如果你在開發分支上新增了 workflow，記得先合併到 main，或者確保 on 的設定有包含該開發分支。

CodeQL 的收費方式主要取決於你的專案性質（公開或私有）以及使用的環境。以下整理 2026 年最新的收費架構：

公開儲存庫 (Public Repositories)

對於開源專案，CodeQL 是完全免費的。

掃描功能：你可以無限制地使用 CodeQL 掃描公開專案，且不收費。
執行成本：如果使用 GitHub 託管的標籤執行器 (GitHub-hosted runners)，在公開專案上執行 Actions 也是免費的。

私有儲存庫 (Private Repositories)

對於公司或個人的私有專案，CodeQL 通常需要付費，其模式分為兩部分：

1. 功能授權費 (GitHub Advanced Security)

CodeQL 屬於 GitHub Advanced Security (GHAS) 套件的一部分。

企業用戶：必須購買 GHAS 授權才能在私有專案啟用 CodeQL。收費通常是根據「活躍提交者」(Active Committer) 數量計算，大約每人每月 30 美元。
個人/小團隊：如果你使用的是 GitHub Free 或 Team 方案，預設無法在私有專案使用 CodeQL。

2. 運算成本 (Actions Minutes)

執行 CodeQL 掃描需要消耗運算資源：

GitHub 託管執行器：會消耗你的 Actions 免費額度（例如 Free 方案每月 2,000 分鐘）。超過額度後，會根據機器規格按分鐘計費。
自託管執行器 (Self-hosted Runners)：從 2026 年 3 月起，GitHub 對於自託管執行器也開始收取每分鐘約 0.002 美元的雲端平台服務費，不再是完全免費。

特別例外與免費方案

學生與教職員：透過 GitHub Student Developer Pack 認證，可以免費獲得許多進階安全功能。
開源貢獻者：如果你是知名開源專案的維護者，有機會獲得免費的 Pro 或更高階授權。
研究用途：CodeQL 的 CLI 工具在非商業的安全研究用途下通常是免費的。

專案類型	CodeQL 功能	GitHub Actions 運算
公開 (Public)	免費	免費
私有 (Private)	需購買 GHAS 授權	消耗分鐘數額度或付費

Max的程式語言筆記