Day 20 - 從 0 到自動化：開啟你的第一個 GitHub Actions 旅程

發表於

前言

在專案開發的過程中，常常會遇到這種情況：

  • 有時候是忘了跑 ESLint，專案裡到處都是紅線。
  • 有時候是格式亂掉，Prettier 沒跑，code review 變成「排版大戰」。
  • 更慘的是，大家都說「我電腦可以跑」，結果一併到 main 就全壞。

這些其實都不是誰的錯，而是我們缺少一個「自動幫我們檢查」的機制。

👉 這就是 CI/CD 登場的時候：

它就像一個不會喊累的機器人，每次你 push 或發 PR，就自動幫你檢查、測試、甚至部署。

今天，我們就來用 GitHub Actions 簡單幫專案加上這個「自動守護者」，開啟 CI/CD 的第一步！

CI / CD 是什麼？有啥好處

  • CI（Continuous Integration，持續整合）
    每次 push 或 PR 時，自動跑測試、檢查程式碼，確保專案隨時健康。
    好處：快速發現 bug、避免合併衝突、提升專案穩定度。
  • CD（Continuous Delivery / Deployment，持續交付/部署）
    • Delivery：確保程式隨時可以部署（但最後一步通常人工按下去）。
    • Deployment：自動一路推到正式環境。
      好處：讓產品更新流程更快、更穩、更少人為失誤。

什麼是 GitHub Actions？

GitHub Actions 是 GitHub 提供的 自動化工作流程服務，可以在 push、PR、發版 tag 等事件觸發時，執行你定義的工作，例如：

  • 跑 Lint / Test / Build
  • 自動部署到 Render、Vercel、AWS
  • 發送通知到 Slack / Discord

同類型工具有哪些？

除了 GitHub Actions，常見的 CI/CD 工具有：

  • GitLab CI/CD – 和 GitHub Actions 很像，但內建在 GitLab。
  • CircleCI / Travis CI – 早期很流行的雲端服務。
  • Jenkins – 傳統自架 CI/CD 工具，彈性高但維護成本大。

✨ 為何選擇 GitHub Actions 入門？

  • 零門檻整合：Repo 在 GitHub，就能直接用。
  • 社群豐富：Marketplace 上有各種現成 actions。
  • 免費額度夠用：對個人專案和開源很友善。
  • YAML 配置直覺：學一次就能套用到其他專案。

GitHub Actions 只負責 CI 嗎？

不是！

  • 它可以跑 CI（測試 / 檢查 / 編譯）。
  • 也能做 CD（自動部署）。

今天我們先聚焦在 CI 自動化檢查，讓專案更安全。

🛠️ 實戰步驟

步驟一：創建 GitHub Actions 工作流程目錄

首先，在專案根目錄創建 .github/workflows 資料夾。

步驟二：創建 CI Workflow 文件

我們建立一個最簡單的 GitHub Actions workflow，包含以下檢查：

  • ✅ 代碼風格檢查 (ESLint)
  • ✅ 格式檢查 (Prettier)
  • ✅ TypeScript 編譯檢查

在剛剛建立的資料夾底下建立 ci.yml檔案內容如下：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
name: CI

# 觸發條件：當有程式碼推送到任何分支，或有 Pull Request 時
on:
  push:
    branches: ["**"]
  pull_request:
    branches: ["**"]

jobs:
  # 代碼品質檢查工作
  code-quality:
    runs-on: ubuntu-latest

    steps:
      # 步驟 1: 檢出程式碼
      - name: 📥 檢出程式碼
        uses: actions/checkout@v4

      # 步驟 2: 設置 Node.js 環境
      - name: 📦 設置 Node.js
        uses: actions/setup-node@v4
        with:
          node-version: "20.17.0"
          cache: "npm"

      # 步驟 3: 安裝依賴
      - name: 📚 安裝依賴套件
        run: npm ci

      # 步驟 4: 執行 Prettier 格式檢查
      - name: 🎨 檢查程式碼格式
        run: npm run format:check

      # 步驟 5: 執行 ESLint 檢查
      - name: 🔍 執行 ESLint 檢查
        run: npm run lint

      # 步驟 6: TypeScript 編譯檢查
      - name: 🔨 TypeScript 編譯檢查
        run: npx tsc --noEmit

詳細說明

1. Workflow 觸發時機

1
2
3
4
5
on:
  push:
    branches: ["**"] # 任何分支有推送時觸發
  pull_request:
    branches: ["**"] # 任何 Pull Request 時觸發

2. 執行環境

  • runs-on: ubuntu-latest → 使用最新的 Ubuntu 環境
  • node-version: '20.17.0' → 使用專案指定的 Node.js 版本

3. 檢查步驟

  1. 格式檢查 → 確保程式碼符合 Prettier 規範
  2. Lint 檢查 → 確保程式碼符合 ESLint 規則
  3. 編譯檢查 → 確保 TypeScript 沒有型別錯誤

如何使用

步驟三：提交並推送到 GitHub

1
2
3
4
5
6
7
8
# 1. 將 workflow 文件加入版本控制
git add .github/workflows/ci.yml

# 2. 提交變更
git commit -m "chore: add GitHub Actions CI workflow"

# 3. 推送到 GitHub
git push

步驟四：查看 Actions 執行結果

  1. 前往你的 GitHub repository

  2. 點擊上方的 “Actions” 標籤

  3. 你會看到 workflow 正在執行或已完成

  4. 點擊任何一次執行可以查看詳細的執行記錄 (這邊可以發現程式碼格式上有些問題) → CI 檢查失敗

  5. 修復關於 migrations 資料夾底下程式碼格式問題 → 目標是讓 CI 能夠正確完整執行

    推薦方法：讓 Prettier 和 ESLint 忽略 migrations 資料夾的檢查

    這是最常見的做法，因為：

    • ✅ migration 是 TypeORM 自動生成的，不應該手動或格式化修改
    • ✅  每次生成新的 migration 都會有相同的問題

    在 .prettierignore 加上

    1
    src/migrations/**/*.ts

    修改 eslint.config.js 加上 ( ignores: ["src/migrations/**/*.ts"] )

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    const js = require("@eslint/js");
    const globals = require("globals");
    const prettier = require("eslint-config-prettier");
    const tsParser = require("@typescript-eslint/parser");
    const tsPlugin = require("@typescript-eslint/eslint-plugin");

    module.exports = [
      {
        // 新增：忽略 migrations 資料夾
        ignores: ["src/migrations/**/*.ts"],
      },
      {
        files: ["**/*.ts"], // 檢查 .ts 檔案
        languageOptions: {
          parser: tsParser, // 用 TypeScript 的解析器
          sourceType: "module", // 支援 ES 模組
          globals: {
            ...globals.node, // Node.js 的全域變數（像 process）
          },
        },
        // ... existing code ...
      },
    ];

  6. 進行 commit 與推送程式碼

    commit : update ESLint/Prettier config to ignore migrations folder

  7. 一樣的方式查看 Github Action

  8. 結果 : 偵測出我們之前測試 ESLint 套件所建立的一個小檔案有問題 testLint.ts

  9. 移除 testLint.ts 後再 push 一次

  10. 結果 : 成功通過 CI 測試啦！

✅ 完成！

到這裡，你已經成功在專案中導入 第一個 GitHub Actions CI Workflow。

從現在開始，每次 push 或發 PR，GitHub 會幫你自動檢查程式碼，確保品質無虞。

補充

如果只想在 main 和 develop 分支執行，可以改成：

1
2
3
4
5
on:
  push:
    branches: ["main", "develop"]
  pull_request:
    branches: ["main", "develop"]

結語

到今天為止，我們已經幫專案加上了第一層保護網：

  • push / PR → 自動跑 ESLint / Prettier / TypeScript 檢查
  • 任何錯誤 → CI 立刻偵測，保持程式碼品質

CI 就像一個安靜但可靠的守護者，幫助團隊維持專案品質。

參考資料

chore: 🤖 add GitHub Actions CI workflow

chore: 🤖 update ESLint/Prettier config to ignore migrations

fix: 🐛 reomve testLint.ts