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 中很難用肉眼發現循環,因此先把依賴關係畫成圖,是實務上最快的捷徑。

以詳細顯示把 runs-on、if、matrix 放進圖中

在 GitHub Actions 視覺化工具勾選「同時顯示詳細資訊」,工作的方框就會多出下列資訊。取消勾選就會回到原本只有工作名稱的圖。

test      → test / runs-on: ubuntu-latest / matrix: 6 (+1 include)
deploy    → deploy / runs-on: self-hosted, linux / if: github.ref == 'refs/heads/main' / environment: production
call      → call / uses: ci.yml@v1
  • runs-on:不論是字串或陣列([self-hosted, linux])都會加上
  • matrix:陣列之間的組合數。include 增加的部分另外寫成 +N include。像 ${{ fromJson(…) }} 這樣的運算式無法計數,因此顯示為 (dynamic)
  • if:去掉條件中的 ${{ }} 後加上,並把該工作的邊框改成虛線。不一定每次都會執行的工作一眼就能看出來
  • uses / environment:呼叫可重複使用工作流程的工作會加上 uses(檔名與標籤),有部署目標的工作會加上 environment
  • 過長的條件會在 60 個字元處截斷,< > " & 會改成實體參照,避免破壞 Mermaid 的語法

進階 SVG 顯示:邊操作邊讀工作之間的關係

除了 Mermaid 圖之外,相依關係也能用**自製的「進階 SVG」**繪製(這是預設的顯示方式;Mermaid 顯示與複製 Mermaid 程式碼仍可照常使用)。

  • 階段由左至右:依 needs 的深度分欄,同一深度的工作垂直排列。也可以為每個階段加上框(標題如 Stage 2 · 3),並為工作種類加上圖示(重複使用、矩陣、部署)
  • 強調最長的相依鏈:關鍵路徑以粗橘線標示,並顯示該鏈 timeout-minutes 的總和(含未設定 timeout 的工作數)
  • 矩陣工作以疊起的方框表示,使用 needs.<job>.outputs 的相依,連線上會標示「outputs」
  • 點擊工作方框可看到 runs-on、步驟名稱與 needs。滑鼠移上去(鍵盤則是聚焦),只會保留該工作上下游的連線
  • 拖曳重新排列:可拖曳方框(或聚焦後用方向鍵)移動。移動期間會隱藏階段的框
  • 圖可縮放到符合寬度、放大縮小,並儲存為 SVG 或 PNG

你輸入的 YAML、顯示選項與移動過的位置,會自動儲存在這個瀏覽器中,下次開啟時可以接著使用。也可以刪除已儲存的內容,或以 JSON 匯出、匯入。不會傳送到伺服器。

常見問題

沒有指定 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 配置出現錯誤時,先畫成圖重新確認執行順序,往往是最快的排查方式。