GitHub Actions 視覺化的圖檔

歡迎來到 YAML 叢林

你團隊的 workflow.yml 現在有多少行了？

CI/CD 一開始通常都很單純。「只要能 Lint，測試，然後打包就好了！」可是隨著產品成長，總會有人加了一段：如果 E2E 測試失敗就發 Slack 通知；另一個人又加了一個：如果遇到某些分支就跳過部署邏輯。不知不覺中，你已經養出了一頭好幾百行的 YAML 怪物。

  build:
    needs: [test-frontend, test-backend, check-format]
  deploy:
    needs: [build, security-scan]

我還記得自己對著 GitHub 漆黑的螢幕發呆，心想：「等等… 前端打包的 Job 真的得等後端測試跑完嗎？」我竟然在自己親手寫的程式碼中迷路了。人類的大腦本來就不適合從純文字中去解讀這麼深層、交錯複雜的依賴結構圖。

牽起隱形的紅線

「我再也沒辦法把這棵抽象的樹狀結構塞進腦子裡了。我需要實際『看』到它。」

這個挫折成為了這套視覺化工具誕生的星火。概念很簡單：你把一大坨 YAML 貼上來，然後聰明的 JavaScript 就會偷偷潛入，解析所有的 needs: 參數，抓住它們的父子關係，並用 Mermaid.js 吐出一張排版絢麗的流程圖。

開發過程中出乎意料最有趣的其實是錯誤處理（Error Handling）。大家都知道 YAML 是個異常狠毒的語言——只要縮排漏掉一個空白，整個結構就會原地引爆。這套工具不會只是冷冰冰地丟給你一句「解析錯誤（Parsing Error）」，我額外花了點心力讓它可以對著你精準吼出「第幾行出錯了」，這樣你才真的找得到自己到底拼錯了什麼。

現在，我們團隊把這套視覺化工具拿來當作對新進開發者進行教育訓練、講解 CI 流程的輔助講義。如果你也有看著 YAML 看到快要發瘋的感覺，把它複製貼上來吧。看見自己寫的邏輯原來長出了一種如此美麗的形狀，或許會讓你心裡稍微好受一點。

變成圖之後，審查的對話就不一樣了

當你用純文字審查 YAML 時，留言難免會飄向瑣碎的語法細節：「這裡的縮排」「這個 needs 陣列」。但只要把它畫成圖，對話的層次就會往上跳一級。「等等，這個資安掃描是不是沒被列進部署的前置條件？」這種針對「設計本身」的指正，會自然而然地浮現出來。

新同事問「我們的 CI 是怎麼跑的？」時也一樣。給對方看一張流程圖，遠比一起捲動幾百行 YAML 來得快。圖既是寫程式的工具，也是向人解釋的共通語言。當你的 CI 開始變得複雜，先把整體畫成圖，往往是最快的捷徑。

常見問題

我貼上的工作流程 YAML 會被傳送到外部嗎？

不會。解析 YAML 與生成圖表都完全在你的瀏覽器內完成。即使內容包含公司內部的 CI/CD 定義、Job 名稱或部署目標，也不會傳送到外部伺服器。

needs 會畫成什麼樣的圖？

它會讀取 needs:，把 Job 之間的父子關係畫成帶箭頭的圖。哪些是串列、哪些是並行、有沒有漏指定依賴，一眼就能看出來，比從頭到尾讀 YAML 更不容易看錯。

生成的圖可以貼到 GitHub 嗎？

可以。複製生成的 Mermaid 程式碼，貼進 README 或文件即可。拿來當作向新成員說明 CI 結構的素材也很合適。

如果 YAML 有錯導致圖無法顯示，該怎麼辦？

多半是縮排跑掉造成的。由於 YAML 只要差一個空白結構就會改變，請檢查 Job 的巢狀層級是否對齊、是否用空白（而非 Tab）縮排。從錯誤訊息指出的那一行附近開始看會比較快。