YAML 語法

部分內容由 LLM 生成,尚未經過人工驗證。

GitHub Actions workflow 檔案的 YAML 語法關鍵字快速參考。

Workflow 基本結構

頂層關鍵字

關鍵字	說明	用途	範例
`name`	Workflow 名稱	在 Actions 介面顯示的識別名稱	`name: CI Pipeline`
`run-name`	執行實例名稱	動態顯示每次執行的名稱（可用表達式）	`run-name: Deploy by @${{ github.actor }}`
`on`	觸發事件	定義何時執行 workflow	`on: push`
`permissions`	權限設定	控制 GITHUB_TOKEN 的存取權限	`permissions: read-all`
`env`	環境變數	全域環境變數（所有 jobs 可用）	`env: NODE_ENV: production`
`defaults`	預設設定	為所有 jobs/steps 設定預設值	`defaults: run: shell: bash`
`concurrency`	並發控制	限制同時執行的 workflow 數量	`concurrency: production`
`jobs`	工作定義	包含一個或多個 job（必填）	`jobs: build: ...`

觸發事件（on）

單一事件

on: push

多事件觸發

on: [push, pull_request, workflow_dispatch]

事件類型與過濾器

關鍵字	說明	範例
`push`	推送代碼時觸發	`on: push: branches: [main]`
`pull_request`	PR 事件觸發	`on: pull_request: types: [opened, synchronize]`
`workflow_dispatch`	手動觸發	`on: workflow_dispatch: inputs: ...`
`schedule`	定時觸發（cron）	`on: schedule: - cron: '0 0 * * *'`
`workflow_call`	被其他 workflow 呼叫	`on: workflow_call: inputs: ...`
`repository_dispatch`	外部 API 觸發	`on: repository_dispatch: types: [custom-event]`

過濾器關鍵字

關鍵字	說明	範例
`branches`	限制分支	`branches: [main, 'releases/**']`
`branches-ignore`	排除分支	`branches-ignore: [staging]`
`tags`	限制標籤	`tags: ['v..*']`
`paths`	限制檔案路徑	`paths: ['src/', '.js']`
`paths-ignore`	排除檔案路徑	`paths-ignore: ['docs/**']`
`types`	事件子類型	`types: [opened, reopened, closed]`

Jobs 定義

Job 層級關鍵字

關鍵字	說明	用途	範例
`runs-on`	執行環境	指定 runner（必填）	`runs-on: ubuntu-latest`
`needs`	依賴關係	定義 job 執行順序	`needs: [build, test]`
`if`	條件執行	根據條件決定是否執行	`if: github.ref == 'refs/heads/main'`
`strategy`	執行策略	矩陣建構、並行控制	`strategy: matrix: node: [14, 16, 18]`
`steps`	步驟列表	包含一系列 step（必填）	`steps: - uses: actions/checkout@v4`
`timeout-minutes`	超時時間	限制 job 最大執行時間	`timeout-minutes: 30`
`continue-on-error`	忽略錯誤	允許 job 失敗但不中斷 workflow	`continue-on-error: true`
`container`	容器執行	在容器中執行 job	`container: node:18`
`services`	服務容器	啟動服務容器（如 Redis、Postgres）	`services: redis: image: redis`
`outputs`	輸出變數	傳遞資料給其他 job	`outputs: version: ${{ steps.get-version.outputs.value }}`
`env`	環境變數	Job 層級環境變數	`env: NODE_ENV: test`
`defaults`	預設設定	Job 層級預設值	`defaults: run: working-directory: ./app`
`concurrency`	並發控制	Job 層級並發限制	`concurrency: deploy-${{ github.ref }}`
`permissions`	權限設定	Job 層級權限覆寫	`permissions: contents: read`

Runs-on 可用值

值	說明
`ubuntu-latest`	Ubuntu 最新版（目前 Ubuntu 22.04）
`ubuntu-22.04`	Ubuntu 22.04
`ubuntu-20.04`	Ubuntu 20.04
`windows-latest`	Windows Server 最新版
`windows-2022`	Windows Server 2022
`macos-latest`	macOS 最新版
`macos-13`	macOS 13 Ventura
`self-hosted`	自託管 runner

Strategy 矩陣建構

關鍵字	說明	範例
`matrix`	矩陣變數	`matrix: os: [ubuntu, windows] node: [14, 16]`
`include`	新增矩陣組合	`include: - os: ubuntu, node: 18, experimental: true`
`exclude`	排除矩陣組合	`exclude: - os: windows, node: 14`
`fail-fast`	快速失敗	任一組合失敗立即停止其他
`max-parallel`	最大並行數	限制同時執行的 job 數量

Steps 定義

Step 層級關鍵字

關鍵字	說明	用途	範例
`name`	步驟名稱	顯示在 logs 中的識別名稱	`name: Install dependencies`
`id`	步驟 ID	唯一識別碼,用於引用輸出	`id: get-version`
`uses`	使用 Action	引用預建 Action	`uses: actions/checkout@v4`
`run`	執行命令	執行 shell 命令	`run: npm install`
`with`	傳入參數	傳遞輸入參數給 Action	`with: node-version: 18`
`env`	環境變數	Step 層級環境變數	`env: API_KEY: ${{ secrets.API_KEY }}`
`if`	條件執行	根據條件決定是否執行	`if: success()`
`continue-on-error`	忽略錯誤	允許 step 失敗但不中斷 job	`continue-on-error: true`
`timeout-minutes`	超時時間	限制 step 最大執行時間	`timeout-minutes: 5`
`shell`	Shell 類型	指定執行命令的 shell	`shell: bash`
`working-directory`	工作目錄	指定命令執行的目錄	`working-directory: ./backend`

Shell 可用值

值	說明	適用平台
`bash`	Bash shell（預設）	Linux, macOS, Windows (Git Bash)
`pwsh`	PowerShell Core	Linux, macOS, Windows
`powershell`	Windows PowerShell	Windows
`cmd`	命令提示字元	Windows
`sh`	POSIX shell	Linux, macOS
`python`	Python 解釋器	所有平台

條件與表達式（if）

常用狀態檢查函式

函式	說明	範例
`success()`	前面所有步驟成功	`if: success()`
`failure()`	任一前面步驟失敗	`if: failure()`
`always()`	無論成功失敗都執行	`if: always()`
`cancelled()`	Workflow 被取消	`if: cancelled()`

常用表達式語法

語法	說明	範例
`${{ ... }}`	表達式語法	`${{ github.ref }}`
`github.event_name`	觸發事件名稱	`if: github.event_name == 'push'`
`github.ref`	Git 引用（分支/標籤）	`if: github.ref == 'refs/heads/main'`
`github.actor`	觸發者用戶名	`${{ github.actor }}`
`secrets.SECRET_NAME`	存取 secret	`${{ secrets.GITHUB_TOKEN }}`
`steps.<step-id>.outputs.<output-name>`	引用 step 輸出	`${{ steps.build.outputs.version }}`

環境與 Secrets

環境變數優先級

Step 層級 env - 最高優先級
Job 層級 env
Workflow 層級 env
系統環境變數 - 最低優先級

預定義環境變數

變數	說明
`GITHUB_TOKEN`	自動產生的驗證 token
`GITHUB_REPOSITORY`	儲存庫名稱（owner/repo）
`GITHUB_REF`	Git 引用（分支/標籤）
`GITHUB_SHA`	Commit SHA
`GITHUB_WORKFLOW`	Workflow 名稱
`GITHUB_RUN_ID`	Workflow 執行 ID
`GITHUB_ACTOR`	觸發者用戶名
`RUNNER_OS`	Runner 作業系統（Linux/Windows/macOS）
`RUNNER_TEMP`	Runner 暫存目錄

Secrets 存取

env:
  API_KEY: ${{ secrets.API_KEY }}

Permissions 權限控制

可設定權限

權限	說明	可用值
`actions`	GitHub Actions 工作流程	`read`, `write`, `none`
`checks`	檢查執行	`read`, `write`, `none`
`contents`	儲存庫內容	`read`, `write`, `none`
`deployments`	部署	`read`, `write`, `none`
`id-token`	OIDC token	`read`, `write`, `none`
`issues`	Issues	`read`, `write`, `none`
`packages`	GitHub Packages	`read`, `write`, `none`
`pull-requests`	Pull Requests	`read`, `write`, `none`
`security-events`	安全事件	`read`, `write`, `none`

快捷設定

permissions: read-all    # 所有權限設為 read
permissions: write-all   # 所有權限設為 write
permissions: {}          # 停用所有權限

其他進階關鍵字

Concurrency 並發控制

concurrency:
  group: ${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: true  # 取消進行中的舊執行

Container 容器執行

container:
  image: node:18
  credentials:
    username: ${{ github.actor }}
    password: ${{ secrets.GITHUB_TOKEN }}
  env:
    NODE_ENV: test
  volumes:
    - /tmp:/workspace
  options: --cpus 2

Services 服務容器

services:
  postgres:
    image: postgres:14
    env:
      POSTGRES_PASSWORD: postgres
    options: >-
      --health-cmd pg_isready
      --health-interval 10s
      --health-timeout 5s
      --health-retries 5
    ports:
      - 5432:5432

Workflow_dispatch 手動觸發輸入

on:
  workflow_dispatch:
    inputs:
      environment:
        description: 'Deployment environment'
        required: true
        type: choice
        options:
          - dev
          - staging
          - production
      debug:
        description: 'Enable debug mode'
        required: false
        type: boolean
        default: false

Workflows 概念