前言

當你開始參與團隊專案，或者想讓自己的開源專案更專業時，你可能會聽到「CI/CD」這個詞。每次 push 程式碼後，自動執行測試、自動檢查程式碼風格、自動部署到伺服器——這些看起來很厲害的自動化流程，其實透過 GitHub Actions 就能輕鬆實現。

本篇文章將帶你認識 GitHub Actions 的核心概念，讓你能夠讀懂專案中的 workflow 設定檔，並撰寫自己的第一個自動化流程。

為什麼需要 CI/CD？

在深入 GitHub Actions 之前，讓我們先理解什麼是 CI/CD。

CI（Continuous Integration，持續整合）

想像一個多人協作的專案：每個人在自己的分支上開發，最後都要合併到主分支。如果沒有自動化檢查，可能會發生：

• 合併後才發現程式碼有語法錯誤
• 測試沒跑過就合併，導致功能壞掉
• 程式碼風格不一致，造成維護困難

CI 的核心理念是：每次程式碼變更都自動執行測試和檢查，及早發現問題。

CD（Continuous Deployment/Delivery，持續部署/交付）

通過 CI 檢查後，CD 負責將程式碼自動部署到測試環境或正式環境，減少人工操作的錯誤和時間成本。

GitHub Actions 是什麼？

GitHub Actions 是 GitHub 內建的自動化平台，讓你可以在特定事件發生時（例如 push 程式碼、建立 Pull Request），自動執行預先定義的任務。

它的優勢包括：

1. 與 GitHub 深度整合：不需要額外設定第三方服務
2. 免費額度充足：公開專案無限免費，私有專案每月有免費額度
3. 豐富的生態系統：有大量現成的 Actions 可以直接使用
4. YAML 設定：使用易讀的 YAML 格式定義流程

核心概念架構

GitHub Actions 的架構可以用以下層級理解：

Workflow（工作流程）
    └── Job（工作）
            └── Step（步驟）
                    └── Action（動作）

讓我們逐一解析。

Workflow（工作流程）

Workflow 是最上層的概念，代表一個完整的自動化流程。它定義了：

• 何時執行（Event trigger）
• 執行什麼（Jobs）

每個 Workflow 對應一個 YAML 檔案，存放在 .github/workflows/ 目錄下。

# .github/workflows/ci.yml
name: CI Pipeline  # Workflow 的名稱

on: push  # 觸發條件：當有 push 時執行

jobs:  # 定義要執行的工作
  # ... jobs 內容
Code language: PHP (php)

Job（工作）

一個 Workflow 可以包含多個 Job，每個 Job 代表一組相關的任務。

重點特性：

• 預設平行執行：多個 Job 會同時執行
• 獨立環境：每個 Job 在獨立的 Runner 上執行
• 可設定相依性：透過 needs 讓 Job 按順序執行

jobs:
  test:  # Job 的 ID
    name: Run Tests  # Job 的顯示名稱
    runs-on: ubuntu-latest  # 執行環境
    steps:
      # ... steps 內容

  deploy:
    name: Deploy
    runs-on: ubuntu-latest
    needs: test  # 等 test job 完成後才執行
    steps:
      # ... steps 內容
Code language: PHP (php)

Step（步驟）

Step 是 Job 中的最小執行單位，按順序執行。每個 Step 可以是：

• 執行 shell 指令：使用 run
• 使用現成的 Action：使用 uses

steps:
  - name: Checkout code  # 步驟名稱
    uses: actions/checkout@v4  # 使用官方 checkout action

  - name: Install dependencies
    run: npm install  # 執行 shell 指令

  - name: Run tests
    run: npm test
Code language: PHP (php)

Runner（執行器）

Runner 是實際執行 Job 的虛擬機器。GitHub 提供多種 hosted runner：

jobs:
  build:
    runs-on: ubuntu-latest  # 指定使用 Ubuntu runner
Code language: PHP (php)

Event Triggers（觸發事件）

Workflow 透過 on 關鍵字定義何時觸發。以下是常見的觸發事件：

push 和 pull_request

最常用的兩個事件：

on:
  push:
    branches: [main, develop]  # 只在這些分支 push 時觸發
  pull_request:
    branches: [main]  # 只在對 main 發 PR 時觸發
Code language: CSS (css)

schedule（定時執行）

使用 cron 語法設定定時任務：

on:
  schedule:
    - cron: '0 0 * * *'  # 每天午夜執行
Code language: PHP (php)

workflow_dispatch（手動觸發）

允許在 GitHub 介面上手動觸發：

on:
  workflow_dispatch:  # 啟用手動觸發按鈕
Code language: PHP (php)

常用的官方 Actions

GitHub 和社群提供了大量現成的 Actions，以下是最常見的幾個：

actions/checkout

幾乎每個 Workflow 都需要的 Action，將程式碼 checkout 到 Runner：

- uses: actions/checkout@v4

actions/setup-node

設定 Node.js 環境：

- uses: actions/setup-node@v4
  with:
    node-version: '20'  # 指定 Node.js 版本
Code language: PHP (php)

actions/cache

快取依賴項，加速執行時間：

- uses: actions/cache@v4
  with:
    path: ~/.npm
    key: npm-${{ hashFiles('package-lock.json') }}
Code language: PHP (php)

實作：建立第一個 Workflow

讓我們實際建立一個簡單的 CI workflow。

步驟 1：建立目錄結構

在專案根目錄建立 .github/workflows/ 資料夾：

mkdir -p .github/workflows

步驟 2：建立 workflow 檔案

建立 .github/workflows/ci.yml：

name: CI

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

jobs:
  build:
    name: Build and Test
    runs-on: ubuntu-latest

    steps:
      - name: Checkout repository
        uses: actions/checkout@v4

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'

      - name: Install dependencies
        run: npm ci

      - name: Run linter
        run: npm run lint

      - name: Run tests
        run: npm test
Code language: HTTP (http)

步驟 3：理解這個 Workflow

讓我們逐行解讀：

1. name: CI：Workflow 的名稱，會顯示在 GitHub Actions 頁面
2. on：定義觸發條件
   • 當 push 到 main 分支時觸發
   • 當對 main 分支發 PR 時觸發
3. jobs.build：定義一個名為 build 的 Job
   • runs-on: ubuntu-latest：使用 Ubuntu 環境執行
4. steps：定義執行步驟
   • checkout 程式碼
   • 設定 Node.js 環境
   • 安裝依賴
   • 執行 linter
   • 執行測試

步驟 4：查看執行結果

Push 程式碼後，可以在 GitHub 的 Actions 頁面查看執行狀態：

1. 進入專案頁面
2. 點擊上方的 “Actions” 標籤
3. 選擇對應的 Workflow 查看詳細日誌

YAML 語法重點

GitHub Actions 使用 YAML 格式，以下是一些常見的語法：

縮排

YAML 使用空格縮排（不能用 Tab），通常使用 2 個空格：

jobs:
  build:        # 2 空格縮排
    steps:      # 4 空格縮排
      - name:   # 6 空格縮排
Code language: PHP (php)

陣列

使用 - 表示陣列項目：

branches:
  - main
  - develop

或使用行內格式：

branches: [main, develop]
Code language: CSS (css)

多行字串

使用 | 保留換行：

- name: Multiple commands
  run: |
    echo "Line 1"
    echo "Line 2"
    npm install
Code language: PHP (php)

總結

本篇介紹了 GitHub Actions 的核心概念：

1. Workflow：定義自動化流程的 YAML 檔案
2. Job：Workflow 中的工作單位，預設平行執行
3. Step：Job 中按順序執行的步驟
4. Runner：執行 Job 的虛擬機器環境
5. Event：觸發 Workflow 的事件

理解這些概念後，你就能讀懂大多數專案中的 workflow 設定檔，也能開始建立自己的自動化流程。

下一篇我們將深入探討如何使用 Secrets 管理敏感資訊，以及如何設定環境變數。

延伸閱讀

• GitHub Actions 官方文件
• Workflow 語法參考
• GitHub Actions Marketplace