GitHub Actions 入門：自動化 Lint、Format 與 Type Check

📌 這是 WeaMind 專案系列的第 2 篇。
本系列以專案為背景，記錄重要的技術實作與經驗分享。

從這篇文章開始，我將啟動一個新的系列。

搭配我正在實作中的 Side Project——WeaMind，寫下一篇又一篇的技術實作心得。

讓我們一起在專案中成長，並獲得更多的開發樂趣。

如標題所示，本文主要介紹 GitHub Actions。不過在此之前，我們得先對 CI 有初步的了解。

什麼是 CI？為什麼需要 CI？

CI 是「Continuous Integration」的縮寫，中文是「持續整合」。

它的核心概念是：當開發人員提交程式碼時，系統可以「自動執行一系列預先定義的檢查流程」，例如檢查程式碼是否與現有程式相容、是否能正常運作。

在軟體開發流程中，我們常常要處理很多重複但又不可忽略的工作：檢查程式碼格式、執行靜態分析、跑單元測試，甚至產生 API 文件等。

如果每次提交都要手動跑一輪，既麻煩又易忘。

這時 CI 就派上用場了。它能在每次 push 或開 PR 時（或其它事件），自動幫我們做這些事，讓問題提早浮現，使得開發流程更加穩健，也能節省大量重複性勞動。

常見的 CI 工具有哪些？

市面上已有不少 CI 工具可以選擇，例如：

Travis CI：老牌工具，但在開源社群中的使用率逐漸下降。
CircleCI：主打高彈性與高度客製化的流程控制。
GitHub Actions：GitHub 官方推出、與 GitHub 無縫整合的 CI/CD 解決方案。

這次我們選擇的是 GitHub Actions，理由很簡單：直接內建於 GitHub、好上手、不用額外註冊帳號。

而且對於「公開倉庫」，GitHub 給的 CI 運行時間額度是——無上限！

即使是私人倉庫，免費用戶也有每月 2000 分鐘，通常很夠用了。

認識 GitHub Actions

GitHub Actions 是 GitHub 提供的 CI/CD 解決方案。

相較於上述提到的其它工具，它誕生的時間算是晚得多。

雖然推出較晚（2019 年才正式上線），但 GitHub Actions 從一開始就內建於 GitHub 平台，整合度高是它的一大優勢。

開發者不需額外設定外部服務，就能快速啟用 CI/CD 流程，對個人開發者或小型專案尤其友善。

你可以透過撰寫一份yaml設定檔，定義「什麼時候要觸發什麼流程」，像是：

每次 push 時跑 Lint
每次 Pull Request 開啟時跑測試

它支援容器、多種語言與工具，而且有非常多現成的 actions 可以直接引用。

這些功能，此刻我們還不需要了解，先著眼於當前的目標即可。

學習 CI 工具最好的方式：從需求開始

必須強調，相比於程式語言、後端框架等工具，CI/CD 服務是更加「工具化」的工具。

意思是說，雖然有使用上的規則，但其中並沒有太多的「道理」可言！

單純就是看各家廠商怎麼制定與規範、設定檔怎麼寫等等。

所以，我認為，學習這類工具，最好的方式就是「直接用用看」！

你不需要一開始就設計一套完整的 CI 流程，只要從最簡單的需求開始，例如：

跑 Lint、跑 Formatter
檢查型別

這正是本文的出發點——用 GitHub Actions 設定一個最小可用的 CI 流程，整合 Lint、Format 與 Type Check。

沒有需求怎麼辦？

前面強調了需求的重要性，絕非隨便說說。

為了學習 GitHub Actions，我也看過不少課程，但沒有真實需求，學完很快就忘了。因為它的各種功能對我來說，都無法產生「具體的連結」。

所以，如果你沒有實際的需求，我有兩個建議：

自己創造需求！就像我們這裡的 side project，這不就有需求了嗎😇
先別學了！事半功倍鵝🪿

第二點不是開玩笑XD，真的，沒需求就先別學了——晚點再說。軟體開發還有無數的領域等著你探索與投入。

回到正題，直接來看專案中如何實作 GitHub Actions CI。

GitHub Actions 實作

我們的小目標是：

只要有人 push 或開 PR，就自動檢查程式碼品質。（這是最常見的 CI 觸發時機）
用以下工具檢查：
- Ruff：作為 Linter 與 Formatter（參考〈Python 開發：RuffLinter、Formatter 介紹 + 設定教學〉）
- Pyright：執行靜態型別檢查（參考〈Pyright 上手指南：Python 型別檢查的新選擇〉）

這些都是我平常在本機開發會執行的操作——無論是透過 VS Code 還是 pre-commit，現在只是搬到 CI 裡執行。

相關文章：Python 開發：pre-commit 設定 Git Hooks 教學

GitHub Action YAML 設定

以下是實際的設定檔內容，放在專案目錄底下的 .github/workflows/ci.yml：

name: Continuous Integration

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

jobs:
  quality-check:
    name: Lint, Format, Type Check, Test
    runs-on: ubuntu-latest
    container:
      image: ghcr.io/astral-sh/uv:python3.12-bookworm-slim

    steps:
      - uses: actions/checkout@v4
      - name: Install dependencies
        run: uv sync --locked
      - name: Lint (ruff)
        run: uv run ruff check . --fix
      - name: Format (ruff format)
        run: uv run ruff format .
      - name: Type check (pyright)
        run: uv run pyright
      - name: Run unit tests
        run: uv run pytest

可以看出，它還跑了單元測試！

我們可以暫時無視這部分，因為測試的相關設定細節更多，之後再另篇討論。

其餘細節也都先略過，我們只看最後的steps部分。

每個run:就是執行一個 CLI 指令，只不過是在 GitHub 的遠端 runner 上執行而已。

這就是 CI 本質：開另一台機器，做一連串你「事先預定」的事情！

執行結果

寫好 yaml 設定檔後，只要你 commit 並 push，GitHub 就會開始跑 CI workflow 了！（每一個設定檔都是一個 workflow）

無論成功或失敗，結果都會顯示在專案的「Actions」分頁：

GitHub Actions 執行結果

這裡是成功的，如果失敗了，GitHub 還會寄信給你——這很重要。

結語：最關鍵的第一步

本文僅對 CI 跟 GitHub Actions 做了基本的介紹，並展示一下我的設定檔。

因為篇幅有限，沒有對所有細節進行完整說明——或許以後！

但這並不妨礙你立刻開始動手。

我認為，在 AI 能夠很好地輔助軟體開發的時代，設定檔的內容大部分都可以由 AI 代勞——當然我們不能對此一無所知😅

最重要的還是：你開始使用這些工具，將它們融入到開發流程中。

我想這才是最關鍵的第一步。

文章目錄