GitHub Actions 的「複雜化」挑戰

GitHub Actions 很強大，但工作流 YAML 會隨著專案成長而越來越肥大。想從數百行程式碼中看懂「哪個 job 在哪個 job 之後執行」，花費的時間往往遠超預期。

GitHub Actions 可視化工具 只要貼上工作流 YAML，就能立即轉換成 Mermaid 依賴關係圖。所有處理都在瀏覽器內完成，敏感的工作流定義不會傳送到伺服器。

GitHub Actions 工作流可視化：精確理解複雜的流水線

needs 如何轉換成圖

可視化完全是根據每個 job 的 needs 欄位建立的。分散在 YAML 各處的依賴關係會被逐一走訪，轉換成 Mermaid 的箭頭。

jobs:
  lint:
    runs-on: ubuntu-latest
  test:
    needs: lint
  build:
    needs: lint
  deploy:
    needs: [test, build]
graph TD
    lint["lint"]
    test["test"]
    lint --> test
    build["build"]
    lint --> build
    deploy["deploy"]
    test --> deploy
    build --> deploy

一眼就能看出 lint 是瓶頸、test 與 build 平行執行、deploy 是匯流點——流水線的整體形狀一目了然。

needs 可以寫成字串，也可以寫成陣列

GitHub Actions 的規格允許 needs 在只有一個依賴時寫成字串，多個依賴時寫成陣列：

needs: lint            # 寫成字串也可以
needs: [lint, test]    # 寫成陣列也可以

可視化工具兩種寫法都能正確處理，但了解這個小細節，能讓您自己讀 YAML 時不會被搞混。

常見的流水線結構模式

把工作流畫成圖之後會發現，大部分其實都是幾種固定模式的組合：

  • 扇出（平行展開）：build 之後 test、lint、security-scan 同時執行——縮短 CI 時間的基本模式
  • 扇入（匯聚）：多個 job 完成後匯聚到 deploy，以 needs: [build, test, lint] 這種方式指定多個依賴
  • Matrix：用 strategy.matrix 把同一個 job 展開成多個版本／作業系統的組合——圖上只是一個節點，實際執行時卻是多個平行 job

畫成圖之後，「明明該平行卻串成序列」「deploy 的 needs 少了品質檢查」這類問題就會浮現出來，成為改善流水線的起點。加速 CI 的具體模式，可參考 GitHub Actions needs 設計模式集。

審查時的具體範例

在下面的配置中，deploy 只相依於 test，因此即使 lint 失敗也可能會進入部署。

jobs:
  lint:
    runs-on: ubuntu-latest
  test:
    runs-on: ubuntu-latest
  deploy:
    needs: [test]
    runs-on: ubuntu-latest

畫成圖表後，lint 會顯得獨立，因此更容易討論「品質檢查是否該納入部署的前提條件」。這也能引導出設計決策——是把 deploy 的 needs 改成 [lint, test] 就好，還是要新增 build job 來共享產物。

循環依賴會被 GitHub Actions 本身擋下來

如果 needs 形成迴圈（A 依賴 B、B 依賴 A），GitHub Actions 就完全無法執行該工作流，並回報錯誤。在數百行 YAML 中很難用肉眼發現循環，因此先把依賴關係畫成圖，是實務上最快的捷徑。

常見問題

沒有指定 needs 的 Job 會如何執行？

沒有 needs 的 Job 會在工作流開始時並行執行。若要控制順序，請用 needs: [job-id] 明確指定相依對象。畫成圖表後，獨立執行的 Job 與循序 Job 的邊界一目了然。

相依關係形成循環會怎樣？

若 needs 形成迴圈，GitHub Actions 將無法執行工作流並回報錯誤。在數百行 YAML 中很難察覺循環，因此將其視覺化為 DAG（有向無環圖）會很有幫助。

把工作流 YAML 貼到外部工具安全嗎？

工作流可能含有密鑰名稱與部署目標等資訊。GitHub Actions 可視化工具 在你的瀏覽器內完成處理，不會將 YAML 傳送到伺服器，因此可安全地將這類檔案繪製成圖。

Matrix 建置會怎麼顯示？

透過 strategy.matrix 展開成多個組合的 job，在定義上仍是同一個 job，因此圖上也只會顯示成一個節點。實際執行時，則會依組合數量平行跑出多個 job，這點請留意。若目的是掌握 needs 的依賴流向，單一節點的呈現方式已經足夠實用。

總結

  • 可視化只是把每個 job 的 needs 轉換成 Mermaid 箭頭，機制本身很單純
  • needs 同時支援字串與陣列兩種寫法
  • 畫成圖之後，能發現「不必要的序列化」「非預期的平行」「循環依賴」
  • 加速 CI 的具體模式，請參考另一篇需求設計模式集文章

當複雜的 job 配置出現錯誤時，先畫成圖重新確認執行順序，往往是最快的排查方式。