ghaction-lis (GitHub Action Listener)
一個輕量級的 CLI 工具，讓你直接在終端機監聽 GitHub Actions 的部署狀態。
再也不用頻繁切換視窗了！你不需要每次 git push 後都打開瀏覽器確認 CI/CD 是否通過。ghaction-lis 能直接在你的終端機內運行，即時回報進度，如果執行失敗，還能立刻找出並印出報錯的 Job 連結！
核心特色
- 零設定 (Zero Config)：自動解析你當前的 Git 專案，完全不需要任何設定檔。
- 無縫認證：支援環境變數與
ghCLI，甚至支援免 Token 的公開專案訪客模式。 - 防止 Race Condition：精準鎖定你剛推上去的
head_sha，絕對不會抓到舊的歷史紀錄。 - 智慧錯誤定位：如果 Action 失敗，會直接在終端機印出精確的報錯網址，點擊即可修復。
安裝與使用方式
我們提供兩種使用方式，您可以根據自己的開發習慣來選擇：
方案一：使用 npx (強烈推薦 )
我們推薦使用 npx 來執行，確保零環境污染且每次都能使用到絕對最新版：
npx ghaction-lis方案二：全域安裝 (Global Install)
如果您希望在任何地方都能直接敲打縮寫指令，可以透過 npm 進行全域安裝：
npm install -g ghaction-lis安裝後，即可直接使用 ghaction-lis 指令。
認證需求
本工具建議提供 GitHub Token 以確保穩定性。我們支援以下三種情境：
- 設定環境變數（優先）：
export GITHUB_TOKEN=你的金鑰 - 使用 GitHub CLI：直接安裝官方
ghCLI 並完成登入 (gh auth login)。 - 無 Token 模式（新手友善）：如果你不想提供 Token，且專案是公開專案 (Public Repo)，工具依然可以運作！但會受限於 GitHub 的 API 限制（每小時 60 次），且若為私有專案 (Private) 則會被 GitHub 拒絕存取並給予友善提示。
使用說明
在任何有設定 GitHub Actions 的專案目錄下，推播程式碼後直接輸入指令：
git push
# 若已全域安裝：
ghaction-lis
# 若不想全域安裝：
npx ghaction-lis參數說明
| 參數 | 說明 |
|---|---|
--open |
部署成功後，自動呼叫系統預設瀏覽器開啟 GitHub 紀錄網頁。 |
--chain <name> |
接力監聽 (Chained Workflow)：在目前的 Action 成功完成後，接續監聽名為 <name> 的下游任務 (例如：--chain "Deploy to AWS")。 |
--pages |
GitHub Pages 懶人包：自動接力監聽 GitHub Pages 的發佈任務 (完全等同於 --chain "pages-build-deployment")。 |
--timeout <number> |
自訂監聽逾時的分鐘數（預設為 30 分鐘）。 |
兩階段/接力部署 (Chained Workflow) 支援
有時候你的部署是分兩段的（例如：推送到 main 會先跑編譯，編譯成功後才觸發另一個叫做 Deploy to AWS 或 GitHub 官方的 pages-build-deployment 的後續任務）。因為 GitHub 將它們視為獨立的兩個事件，一般工具無法跨任務監聽。
ghaction-lis 完美解決了這個痛點！你可以使用 --chain 或 --pages 來實現無縫的接力等待：
針對 GitHub Pages 使用者（懶人包）：
npx ghaction-lis --pages --open針對自訂下游任務的使用者：
# 假設你的第二階段任務名稱叫做 "Release to Production"
npx ghaction-lis --chain "Release to Production"程式會先監聽第一階段任務，等它成功後，自動鎖定並接續等待設定的第二階段任務完成！
終端機情境範例
情境一：執行成功 (Success)
$ git add .
$ git commit -m "chore: 測試一下流程"
$ git push
$ ghaction-lis
✔ 成功鎖定專案：liwenchiou/ghaction-lis
✔ 鎖定目標：Run ID #27612172810 (chore: 測試一下流程)
⠋ GitHub Action 執行中 (in_progress)，已耗時 12s...
✔ Action 執行成功！🎉 (總耗時: 21s)
🔗 點擊查看紀錄: https://github.com/liwenchiou/ghaction-lis/actions/runs/27612172810情境二：執行失敗 (Failure)
$ git add .
$ git commit -m "test: 模擬打包出錯"
$ git push
$ ghaction-lis
✔ 成功鎖定專案：liwenchiou/ghaction-lis
✔ 鎖定目標：Run ID #27612307032 (test: 模擬打包出錯)
⠋ GitHub Action 執行中 (in_progress)，已耗時 18s...
✖ Action 執行失敗！🔥 (結論: failure, 總耗時: 27s)
❌ Job [test-run] 發生錯誤
🔗 點擊查看紀錄: https://github.com/liwenchiou/ghaction-lis/actions/runs/27612307032/job/81639950470情境三：未提供 Token 且為私有專案 (Private Repo)
$ git add .
$ git commit -m "fix: update private code"
$ git push
$ ghaction-lis
⚠ 未偵測到 GitHub Token！將以「未登入」身分呼叫 API。
👉 注意：這僅適用於「公開專案 (Public)」，且受限於 GitHub 每小時 60 次的呼叫限制...
✔ 成功鎖定專案：liwenchiou/my-private-repo
- 正在抓取本地最新 Commit Hash...
✖ 發生未預期的系統錯誤！
👉 提示：GitHub 拒絕了存取 (Not Found)。
這通常是因為這是一個「私有專案 (Private Repo)」，而您目前處於未登入狀態。
請設定環境變數 GITHUB_TOKEN，或執行 `gh auth login` 來取得存取權限！最佳實踐：即插即用 (Plug & Play)
最順暢的體驗是把工具和你的發佈指令綁定在 package.json 中。
我們強烈推薦在這裡使用 npx，這樣未來其他開發者拉下專案後，不需要額外安裝任何套件就能直接享受到優雅的部署流程：
{
"scripts": {
"deploy": "git push && npx ghaction-lis"
}
}設定好之後，未來只要執行 npm run deploy，終端機就會幫你自動完成推播與即時監聽！
授權條款
MIT License