GitHub Actions CI/CD 自動化部署完整教學：從零開始打造部署流水線

什麼是 CI/CD？為什麼你需要它？

如果你還在手動跑測試、手動打包、手動部署到伺服器，那你真的需要花 10 分鐘讀完這篇文章。CI/CD 是 Continuous Integration（持續整合）和 Continuous Deployment（持續部署）的縮寫，簡單來說就是把那些你每次發版本都要重複做的事情，全部交給機器自動完成。

我自己的經驗是，在導入 CI/CD 之前，每次部署都像是在拆炸彈——手動操作 10 個步驟，少一個就會出問題。導入之後，我只需要 git push，剩下的事情全部自動搞定。今天我就用 GitHub Actions 來帶你從零開始建立一條完整的部署流水線。

GitHub Actions 基本概念

在開始寫 workflow 之前，你需要先搞懂三個核心概念：

• Workflow（工作流程）：一個自動化的完整流程，用 YAML 檔案定義，放在 .github/workflows/ 目錄下
• Job（工作）：一個 workflow 裡面可以有多個 job，每個 job 跑在獨立的虛擬機（runner）上。Job 之間預設是平行執行的
• Step（步驟）：每個 job 裡面的具體操作，可以是執行 shell 指令或使用別人寫好的 action

你可以把它想像成一條工廠的生產線：Workflow 是整條產線，Job 是不同的工作站，Step 是每個工作站裡的具體動作。Runner 就是實際執行的機器，GitHub 提供免費的 Ubuntu、Windows 和 macOS runner。

Workflow YAML 語法詳解

讓我用一個最基本的範例來解釋 YAML 的結構：

name: CI Pipeline

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

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - 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 tests
        run: npm test

逐行解釋：name 是 workflow 名稱；on 定義觸發條件；jobs 定義所有工作；runs-on 指定 runner 的作業系統；steps 按順序執行的步驟。注意 YAML 對縮排非常敏感，一定要用空格不是 tab。

觸發條件設定

GitHub Actions 支援非常多種觸發方式：

on:
  push:
    branches: [main, develop]
    paths:
      - 'src/**'
      - 'package.json'
  pull_request:
    branches: [main]
  schedule:
    - cron: '0 2 * * 1'
  workflow_dispatch:

• push / pull_request：最常見，可以限定分支和路徑
• schedule：用 cron 語法設定排程
• workflow_dispatch：手動觸發按鈕

我的建議是：開發階段 push 到任何分支都觸發 CI（跑測試），但 CD（部署）只在合併到 main 時才觸發。

自動化建置與測試

CI 最核心的價值就是自動跑測試：

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
          cache: 'npm'
      - run: npm ci
      - run: npm run lint
      - run: npm run test -- --coverage
      - name: Upload coverage
        uses: actions/upload-artifact@v4
        with:
          name: coverage-report
          path: coverage/

注意 cache: 'npm' 可以快取 node_modules，讓後續的執行速度快很多。

Docker 建置與雲端部署

如果你的專案是用 Docker 容器化部署，CI/CD 裡當然也要包含 Docker 映像檔的建置和推送：

jobs:
  docker:
    runs-on: ubuntu-latest
    needs: test
    steps:
      - uses: actions/checkout@v4
      - name: Login to Docker Hub
        uses: docker/login-action@v3
        with:
          username: ${{ secrets.DOCKER_USERNAME }}
          password: ${{ secrets.DOCKER_PASSWORD }}
      - name: Build and push
        uses: docker/build-push-action@v5
        with:
          context: .
          push: true
          tags: |
            myapp:latest
            myapp:${{ github.sha }}

needs: test 確保測試通過才會開始建置。打兩個 tag：latest 和 commit SHA，方便追蹤版本。

部署到雲端的方式因平台而異。Vercel 可以用 amondnet/vercel-action，AWS 用 aws-actions/configure-aws-credentials。如果你用 Kubernetes，可以用 kubectl apply 來更新部署。

Secrets 與環境變數管理

安全性是 CI/CD 絕對不能忽略的一環。GitHub Secrets 讓你安全地儲存敏感資訊：進入 repo Settings → Secrets and variables → Actions → New repository secret。

幾個安全最佳實踐：

• 絕對不要在 YAML 裡面硬寫密碼或 API Key
• 使用 Environment 管理不同環境的變數（staging vs production）
• 定期輪換密鑰，特別是有人離開團隊時
• 用 OIDC 取代長期 credentials：AWS 和 GCP 都支援

Matrix 建置與快取加速

當你的專案需要在多個環境測試，matrix 策略就派上用場了：

jobs:
  test:
    runs-on: ${{ matrix.os }}
    strategy:
      matrix:
        os: [ubuntu-latest, windows-latest]
        node-version: [18, 20, 22]
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: ${{ matrix.node-version }}
          cache: 'npm'
      - run: npm ci
      - run: npm test

這會自動產生 2x3 = 6 個並行的 job。搭配 actions/cache@v4 可以進一步加速，讓 CI 執行時間減少 50% 以上。

如果你想了解更多關於 Docker 容器化的基礎知識，可以搭配這篇一起閱讀。

總結

建立 CI/CD 流水線的步驟：建立 .github/workflows/ci.yml → 設定觸發條件 → 加入測試步驟 → 設定 Secrets → 加入 Docker 建置 → 加入自動部署 → 設定快取加速。

CI/CD 不是一次設定就完美的東西，它需要隨著專案演進持續優化。但只要你踏出第一步，把最基本的自動測試和部署跑起來，你就會發現再也回不去手動部署的日子了。趕快去建立你的第一個 workflow 吧！