gh-local

gh-local 工具為開發人員提供了一個強大的本地環境，用於直接在本地執行和調試 GitHub Actions CI 工作流程。透過在 Docker 容器內利用 nektos/act 框架，您可以模擬 GitHub 通常託管的確切 CI 環境，從而在處理複雜的工作流程檔案或排除 CI 故障時顯著縮短反饋循環。此工具非常適合需要確保 YAML 配置、環境變數和 Shell 腳本在提交程式碼前按預期運作的軟體工程師。

• 使用 catthehacker/ubuntu:act-latest 映像檔執行特定作業或完整的工作流程套件，以確保與標準 GitHub 託管執行器的相容性。

• 支援本地測試環境配置，透過 --container-architecture 標誌確保在 Apple Silicon 和其他架構上的執行一致性。

• 提供實時進度監控與自動化日誌追蹤，直接向您的會話報告 npm 安裝、建置階段和測試執行等步驟的結果。

• 當工作流程失敗時，提供對錯誤輸出的深度檢查，讓您能在幾分鐘內在本地修改並重新測試配置。

• 在執行前請確保已安裝並啟動 Docker Desktop 與 act CLI；若缺少依賴項，系統將提供安裝指南。

• 請注意，雖然 act 模擬了大多數操作，但它不支援 GitHub 的原生構件（artifact）上傳；這些步驟可能會失敗或被設計為跳過。

• 指定目標作業或工作流程檔案以優化執行時間；若未指定，代理程式預設為 .github/workflows/ci.yml。

• 此工具尊重工作流程 YAML 中定義的環境變數，從而實現本地環境與遠端環境之間的無縫對等。

• 使用此工具識別 CI 流水線中的腳本錯誤、缺少依賴項或路徑問題，無需浪費 GitHub 的執行時間，也不會用反覆試錯的提交來污染您的提交歷史。