雖然可恥但很有用的技術 - ADO Pipeline 客製報表呈現頁面
上禮拜在改 Azure DevOps 的 Pipeline，因為客戶遇到一個很實際的問題。
用戶抱怨，每次 Pipeline 跑完，他們團隊的 PM 和相關人等都跑來問：「這次測試過了幾個？Coverage 多少？部署有沒有成功？Sonar 掃描的報表結果如何?」
苦主耐心地一一回答：「這些資訊都在 Pipeline 的 tasks 裡面啊，你們自己點進去看就好。」
但是，這些大爺們從來不想自己去一個一個 tasks 去點，他們希望有個「一目了然」的整合頁面，能直接看到他們想要的重點數字就好。
『就算我說服了他們，他們也真的自己去看，但沒多久又在 LINE 上問我：那個 Log 到底是什麼意思？這個掃描報告要在哪裡找?』
就這樣『來來回回，他們累了，我也累了。』 苦主無奈地說。
需求很簡單：給我一個摘要頁面就好
大爺們最後跟苦主說：「你能不能幫我們在 pipeline 裡面弄一個 Summary 頁面？我們只要打開就能看到重點數字，不用再去翻那些 log?」
恩恩，我被問到的就是這個…
Pipeline 跑完之後，能不能有個漂亮的摘要頁面，一進來就看到重點：
- 測試通過幾個、失敗幾個、Coverage 趨勢
- 部署到哪個環境、- 有沒有什麼重要的警告
- 源碼掃描報告的摘要是如何?
- 自動化測試結果? 能不能上正式機?
- …
就這樣。
說的很簡單，要蒐集到需要的資訊似乎也還算容易。
但問題是，要怎麼把這些資訊「塞」進 Azure DevOps 的 Pipeline Summary 頁面？
然後我發現了個神奇的東西
在翻 Azure DevOps 的文件時，我發現一個很有趣的機制。
你知道那些客製化的 Extensions 是怎麼樣讓你在 Pipeline 的 Summary 頁面看到額外的資訊(例如掃描報告、測試報告)的嗎?
類似底下這樣：
答案可能會讓你傻眼，不是呼叫什麼 REST API、不用設定什麼 Token、也不用安裝套件。
ADO 用的方法超級簡單：監聽你在 Build Agent 裡面的 console 輸出。
對，就是 stdout。
你只要在 Pipeline 運行的 script 裡面 echo 一行特定格式的字串：
echo "##vso[task.uploadsummary]/path/to/summary.md"
ADO 的 agent 就會看到，然後幫你把那個 markdown 檔案附加到 Pipeline Summary 頁面。(像是上圖那樣)
第一次看到這個，我的反應是：「什麼？這做法也太 Low 了吧？」
為什麼這設計很聰明？
但其實，這似乎又是一個非常簡單且聰明的設計。
因為不管你用 Python、Node.js、PowerShell、還是 bash，只要能印東西到 console，就能用。
完全不用去煩惱「我要先安裝什麼 SDK」、「這個套件版本對不對」、「跨平台怎麼辦」…的問題。
Debug 超級簡單
出問題？直接看 console 輸出就知道了。
不像呼叫 API 還要去看 response、處理 authentication、搞什麼 retry 機制。stdout 就是所見即所得，字串格式打錯了？改一改再跑就好。
穩到不行
這個機制從 TFS 時代就有了，到現在 Azure DevOps 還在用，而且一點問題都沒有。
因為整個 contract 太簡單了，就一個字串格式。不像 API 要升版、要改 schema、要做什麼 breaking change。這個十幾年了根本不會壞。
沒有任何額外成本
你的 script 本來就會印 log 吧？現在只是多印幾行特定格式的訊息而已。
不用發 HTTP request、不用開 connection、agent 本來就在聽 stdout，順便認一下這些特殊指令，就這樣。
具體怎麼用？
你只需要在pipeline中，加入一個 step，設法產生你想要的 summary 檔案(markdown 格式)，然後 echo 那行指令就好。
類似底下這樣：
steps:
- powershell: |
#建立markdown內容
$md = @"
# 🧪 CI 自動化報告
這份報告由 **Azure DevOps CI Pipeline 自動產生**，
....
"@
# 存成檔案
$path = "$(Build.ArtifactStagingDirectory)/report.md"
$md | Out-File -Encoding UTF8 $path
# 重點就這一行
Write-Host "##vso[task.uploadsummary]$path"
displayName: 'PowerShell Script'
就這樣。
然後 pipeline 跑完，你打開 Summary 頁面，就會看到你整理好的報表和結果。
PM 和 閒雜人等再也不會來煩你了。
不用寫什麼 Extensions、不用呼叫 API、不用去求 DevOps/SRE Team 開權限，你直接在 Pipeline 中就可以自己搞定!。
雖然可恥但很有用
老實說，這個設計乍看之下真的很 Low。
現在什麼都講 RESTful API、什麼都要來個 Extensions。結果你告訴我，ADO 是用監聽 stdout 來執行指令？
這不是 80 年代的做法嗎？
但TMD，結果居然是好用到不行。
這讓我想起日劇《月薪嬌妻》的經典台詞：「雖然可恥但有用」（逃げるは恥だが役に立つ）。
工程師常常有個毛病，就是覺得技術一定要夠炫、架構一定要夠潮。結果搞了一堆複雜的設計，最後維護起來集體痛苦到爆。
但你看 ADO 這個設計，簡單到不行，但就是能解決問題。
這才是好的設計吧？ 還記得 Unix philosophy 中的：「Write programs that do one thing and do it well. Write programs to work together. Write programs to handle text streams, because that is a universal interface.」
頗有異曲同工之意。
後記
後來我建議客戶把這個簡單的機制加到主要的 Pipeline 裡面。
現在每次 build 完，團隊成員打開 Summary 頁面，就能直接看到他們想要的資訊。測試結果、Coverage、部署狀態，一目了然。 PM 不用再來問數字了、QA 也不用翻 log 了。
這個簡單到有點可恥的設計，就這樣解決了團隊的大問題。
但有時候真的是這樣，不用搞什麼高大上的架構，簡單的解法反而最有效。
下次當你在設計系統的時候，或許可以問問自己：我是不是把事情搞得太複雜了？有沒有更簡單的做法？
說不定答案就在那些你覺得「有點 Low」的地方。
留言