Skip to content

建立 2026-09-15 更新 2026-09-15

Workflow 怎麼寫

一份 workflow 就是一個 YAML 檔，放在儲存庫的 .github/workflows/，副檔名用 .yml 或 .yaml。檔名自己看懂即可，例如 ci.yaml、test.yml。

GitHub 讀到檔案後，會依 on 決定何時跑、依 jobs 決定跑什麼。語法不多，但層級要記清楚，否則縮排錯一行就整份不跑。

四層結構

workflow          一份 YAML 檔
 └── job          一組在同一台機器上跑的步驟
      └── step    一個動作：用現成 action，或自己 run 指令

最小可跑的例子：

name: hello

on:
  push:
    branches: [main]
  workflow_dispatch:

jobs:
  greet:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v5

      - name: Print a message
        run: echo "hello from GitHub Actions"
欄位 作用
name 顯示在 Actions 分頁的名稱，可省略
on 觸發條件。push 是推送時；pull_request 是開／更新 PR 時；workflow_dispatch 允許在網頁或 gh workflow run 手動執行
jobs.<id> 一個 job 的識別名，只能用字母、數字、_、-
runs-on 跑在哪種機器。入門用 ubuntu-latest 即可
steps 由上往下執行。任一步失敗，後面預設不會跑
uses 引用 Marketplace 上的 action，例如 checkout 程式碼
run 在 runner 上執行 shell 指令

uses: actions/checkout@v5 幾乎每份 CI 都會寫：沒有它，虛擬機是空的，你的 repo 檔案不在裡面。版本釘在 @v5 這類標籤，避免某天 major 更新把流程弄斷。

觸發條件怎麼選

  • 推到 main 就建置／佈署：on.push.branches: [main]
  • 每個 PR 都跑測試：on.pull_request
  • 兩者都要：把 push 與 pull_request 並列
  • 只想偶爾手動跑：加 workflow_dispatch

路徑過濾可避免改 README 也觸發重型測試，例如：

on:
  push:
    paths:
      - "src/**"
      - "pyproject.toml"

環境變數與表達式

步驟裡可用 env 設變數；GitHub 也提供 context，例如 ${{ github.actor }}、${{ github.ref }}。

- name: Show who triggered this
  run: echo "triggered by ${{ github.actor }}"

密鑰不要寫在 YAML 裡，用 ${{ secrets.NAME }}，下一頁會說明。

寫完怎麼知道有沒有跑

  1. 把 YAML commit 並 push。
  2. 打開 repo 的 Actions 分頁，應出現一次 run。
  3. 或在本機：gh run list、gh run watch。

第一次加 workflow 若沒出現，檢查檔案是否真的在 .github/workflows/、YAML 縮排是否用空白（不要用 tab），以及 on 是否包含你剛剛做的那個事件。

相關資料