本文提到的工具
邊閱讀邊在瀏覽器中開啟工具,立即試試整個流程。
GitHub Actions 的「複雜化」挑戰
GitHub Actions 很強大,但工作流 YAML 會隨著專案成長而越來越肥大。想從數百行程式碼中看懂「哪個 job 在哪個 job 之後執行」,花費的時間往往遠超預期。
GitHub Actions 可視化工具 只要貼上工作流 YAML,就能立即轉換成 Mermaid 依賴關係圖。所有處理都在瀏覽器內完成,敏感的工作流定義不會傳送到伺服器。

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