設定 GitHub Actions 工作流程

10 分鐘

在這裡，您將瞭解工作流程檔案中的一些常見組態。您也會探索事件類型類別、停用和刪除工作流程，以及使用特定版本的動作，以取得安全性最佳做法。

針對已排定事件設定要執行的工作流程

如先前所述，您可以設定在 GitHub 上發生特定活動時、在 GitHub 以外的發生事件時，或依排程時間執行工作流程。 schedule 事件可讓您使用 POSIX cron 語法，以觸發工作流程，在特定的 UTC 時間執行。此 Cron 語法有五個 * 欄位，而且每個欄位代表一個時間單位。

圖形顯示五個時間單位的欄位，以用於排程工作流程檔案中的事件。

例如，如果您想要每隔 15 分鐘執行工作流程一次， schedule 事件看起來會像下列範例：

on:
  schedule:
    - cron:  '*/15 * * * *'

而且，如果您想要在每個星期天的早上 3:00 執行工作流程，schedule 事件看起來如下所示：

on:
  schedule:
    - cron:  '0 3 * * SUN'

您也可以使用運算子來指定值的範圍，或是撥入排程的工作流程。執行排程工作流程的最短間隔是每五分鐘一次，且工作流程會根據預設或基底分支上的最新認可來執行。

針對手動事件設定要執行的工作流程

除了已排定事件以外，您還可以使用 workflow_dispatch 事件手動觸發工作流程。此事件可讓您使用 GitHub REST API，或在 GitHub 上的存放庫內選取 [動作] 索引標籤中的 [執行工作流程] 按鈕，來執行工作流程。使用 workflow_dispatch，您可以選擇要在哪個分支上執行工作流程，並設定 GitHub 在 UI 中作為表單元素呈現的可選的 inputs。

on:
  workflow_dispatch:
    inputs:
      logLevel:
        description: 'Log level'     
        required: true
        default: 'warning'
      tags:
        description: 'Test scenario tags'

除了 workflow_dispatch 之外，您還可以使用 GitHub API 來觸發稱為 repository_dispatch 的 Webhook 事件。此事件可讓您針對 GitHub 外部發生的活動觸發工作流程。它基本上是向您的存放庫發出的 HTTP 要求，要求 GitHub 從動作或 Webhook 觸發工作流程。使用此手動事件需要執行兩件事：將 POST 要求傳送至 GitHub 端點 /repos/{owner}/{repo}/dispatches，要求本文中包含 Webhook 事件名稱，並設定您的工作流程使用 repository_dispatch 事件。

curl \
  -X POST \
  -H "Accept: application/vnd.github.v3+json" \
  https://api.github.com/repos/octocat/hello-world/dispatches \
  -d '{"event_type":"event_type"}'

on:
  repository_dispatch:
    types: [opened, deleted]

針對 Webhook 事件設定要執行的工作流程

最後，您可以設定在 GitHub 上發生特定 Webhook 事件時要執行的工作流程。您可以從多個 Webhook 活動觸發大部分的 Webhook 事件。如果 Webhook 有多個活動存在，您可以指定活動類型來觸發工作流程。例如，您可以針對 check_run 事件執行工作流程，但僅適用於 rerequested 或 requested_action 活動類型。

on:
  check_run:
    types: [rerequested, requested_action]

Repository_dispatch

repository_dispatch 是 GitHub Actions 中的自定義事件，可讓外部系統（甚至其他 GitHub 工作流程）將 POST 要求傳送至 GitHub API，以手動觸發工作流程。它可讓您彈性自動化，並與需要啟動存放庫中工作流程的外部工具、腳本或系統整合。

使用案例

從外部 CI/CD 工具觸發工作流程。
協調多存放庫部署（例如，存放庫 A 完成組建→觸發存放庫 B）。
根據外部事件啟動自動化 (Webhook、監視警示、GitHub 外部的 CRON 作業)。
在存放庫或 monorepos 內鏈結工作流程執行。

監聽 repository_dispatch 的範例工作流程

name: Custom Dispatch Listener

on:
  repository_dispatch:
    types: [run-tests, deploy-to-prod]  # Optional filtering

jobs:
  run:
    runs-on: ubuntu-latest
    steps:
      - name: Echo the payload
        run: |
          echo "Event type: ${{ github.event.action }}"
          echo "Payload value: ${{ github.event.client_payload.env }}"

重要元素：

類型：選擇性。定義自定義事件類型，例如 run-tests、 deploy-to-prod等等。
github.event.client_payload：存取分派事件中傳遞的任何其他自定義數據。
github.event.action：所傳送的 event_type 名稱。

透過 API 觸發事件

您必須將 POST 要求傳送至 GitHub REST API v3 端點：

POST https://api.github.com/repos/OWNER/REPO/dispatches

授權

需要具有存放庫範圍的個人存取權杖 (PAT)。
針對組織，請確定權杖的適當存取設定。

範例命令結構

curl -X POST \
  -H "Accept: application/vnd.github+json" \
  -H "Authorization: token YOUR_GITHUB_TOKEN" \
  https://api.github.com/repos/OWNER/REPO/dispatches \
  -d '{"event_type":"run-tests","client_payload":{"env":"staging"}}'

承載結構

{
  "event_type": "run-tests",
  "client_payload": {
    "env": "staging"
  }
}

參數

領域	類型	說明	為必填項目
`event_type`	字串	事件的自定義名稱。此名稱會映射至您工作流程觸發器中的類型值	是的
`client_payload`	物件	將自訂數據傳送至工作流程的任意 JSON 負載（github.event.client_payload）	否

Repository_dispatch參數明細

對 GitHub API 端點提出 POST 要求時，您必須傳遞具有兩個主要參數的 JSON 主體：

事件類型
client_payload

事件類型

您定義的必要自訂字串。 GitHub 會將此值視為分派的「動作」或「類型」。它用來識別有哪些項目觸發了工作流程，並篩選那些正在監聽特定類型的工作流程。

格式：
- 類型：字串
- 範例：“deploy”、“run-tests”、“sync-db”、“build-docker”
在工作流程中使用：用於接聽特定事件類型，以及存取工作流程內的值。這有助於重複使用單一工作流程以供多個用途使用，並讓自動化更有組織且事件導向。
範例：

- name: Print event type
  run: echo "Event type: ${{ github.event.action }}"

client_payload

自由格式的 JSON 物件，可讓您連同分派一起傳送自定義數據。您可以定義結構，並可在工作流程內取用。

格式：
- 類型：物件
- 自定義鍵和值
在工作流程中使用：此對象用於多環境部署、版本化發行，或從另一個系統或管線中傳遞上下文內容，並啟用類似於輸入參數的參數化工作流程。
範例：

- name: Show payload values
  run: |
    echo "Environment: ${{ github.event.client_payload.env }}"
    echo "Version: ${{ github.event.client_payload.version }}"

範例承載明細

{
  "event_type": "deploy-to-prod",
  "client_payload": {
    "env": "production",
    "build_id": "build-456",
    "initiator": "admin_user",
    "services": ["web", "api", "worker"]
  }
}

使用條件關鍵字

在您的工作流程檔案中，您可以存取內容資訊和評估運算式。雖然運算式通常與工作流程檔案中的條件式 if 關鍵字一起使用，以判斷是否應該執行步驟，但您可以使用任何支援的內容和運算式來建立條件式。請務必知道，在工作流程中使用條件時，您必須使用特定的語法 ${{ <expression> }}。此語法會指示 GitHub 評估表達式，而不是將它視為字串。

例如，工作流程使用if條件來檢查github.ref（觸發工作流程執行的分支或標籤 ref）是否符合refs/heads/main。為了繼續，工作流程看起來會像這樣：

name: CI
on: push
jobs:
  prod-check:
    if: github.ref == 'refs/heads/main'
    runs-on: ubuntu-latest
    steps:
      ...

請注意，在此範例中，語法缺少 ${{ }}。透過某些表達式，例如 if 條件式，您可以省略運算式語法。 GitHub 會自動評估其中一些常見的運算式，但您可以一律加入這些運算式，以免忘記 GitHub 會自動評估那些運算式。

如需工作流程語法和運算式的詳細資訊，請參閱 GitHub Actions 的工作流程語法。

停用和刪除工作流程

將工作流程新增至存放庫之後，您可能會遇到想暫時停用工作流程的情況。您可以在 GitHub 或透過 GitHub REST API 停止觸發工作流程，而不需要從存放庫中刪除檔案。當您要再次啟用工作流程時，便可以使用相同的方法輕鬆地完成啟用。

螢幕擷取畫面顯示在 GitHub 上停用工作流程。

停用工作流程在下列某些情況下很有用：

工作流程的錯誤產生太多或錯誤的要求，對外部服務造成負面影響。
您想要暫停非關鍵性的工作流程，該工作流程在您的帳戶上耗用太多時間。
您想要暫停正在向已關閉服務提出要求的工作流程。
您正在處理分支，且您不需要某些工作流程包含的所有功能 (例如，排程的工作流程)。

您也可以在 [動作] 索引標籤內的 GitHub UI 中，或使用 GitHub API 端點 DELETE /repos/{owner}/{repo}/actions/runs/{run_id}，取消進行中的工作流程執行。請記住，當您取消工作流程執行時，GitHub 會取消該執行中的所有作業和步驟。

使用組織的樣板化工作流程

如果您有多個小組在組織內使用的工作流程，則不需要為每個存放庫重新建立相同的工作流程。相反地，您可以使用組織存放 .github 庫中定義的工作流程範本來提升整個組織的一致性。組織內的任何成員都可以使用組織範本工作流程，而該組織內的任何存放庫都可以存取這些工作流程範本。

您可以導覽至組織內存放庫的 [動作] 索引標籤，選取 [新增工作流程]，然後尋找標題為「依組織名稱建立的工作流程」的組織工作流程範本，來尋找這些工作流程。例如，名為Mona的組織具有範本工作流程，如下所示。

螢幕擷取畫面顯示名為「問候和分類」的範本組織工作流程圖 (由 Mona 製作)。

使用特定版本的動作

參考工作流程中的動作時，建議您參考該動作的特定版本，而不只是動作本身。藉由參考特定版本，可防止將非預期的變更推送至可能會中斷工作流程的動作。此處有幾種方式可供您參考特定版本的動作：

steps:    
  # Reference a specific commit
  - uses: actions/setup-node@c46424eee26de4078d34105d3de3cc4992202b1e
  # Reference the major version of a release
  - uses: actions/setup-node@v1
  # Reference a minor version of a release
  - uses: actions/setup-node@v1.2
  # Reference a branch
  - uses: actions/setup-node@main

某些參考比其他參考更安全。例如，參考特定分支會根據該分支的最新變更來執行該動作，而這不一定是您想要的動作。藉由參考特定版本號碼或認可 SHA 雜湊，您將對要執行的動作版本更加明確。為了更加穩定和安全，我們建議您在工作流程中使用已發佈動作的認可 SHA。

意見反應

此頁面對您有幫助嗎？