GitHub CLI (gh) 技能
使用 gh CLI 從終端機與 GitHub 儲存庫、議題、拉取請求及 GitHub Actions 工作流程互動。
先決條件
確認已安裝 gh 並完成驗證:
gh --version
gh auth status
若未驗證,請執行 gh auth login 並依照提示操作。
核心工作流程
議題管理
# 列出議題
gh issue list # 目前儲存庫中的開放議題
gh issue list --state all # 所有議題(包含已關閉)
gh issue list --assignee @me # 指派給您的議題
gh issue list --label "bug" # 依標籤篩選
# 建立議題
gh issue create -t "標題" -b "說明"
gh issue create -t "標題" --label "bug,priority:high" --milestone "milestone-1"
gh issue create # 互動模式
# 檢視/更新議題
gh issue view 123 # 檢視議題詳細資訊
gh issue view 123 --web # 在瀏覽器中開啟
gh issue edit 123 --add-label "in-progress"
gh issue close 123
gh issue reopen 123
# 新增留言
gh issue comment 123 -b "目前正在處理"
分支與提交工作流程
# 建立功能/修正分支
git checkout -b feature/my-feature
git checkout -b fix/issue-123
git checkout -b draft/wip-experiment
# 暫存並提交變更
git add .
git commit -m "feat: 新增功能"
git commit -m "fix: 解決 issue #123"
# 推送分支至遠端
git push -u origin feature/my-feature
拉取請求管理
# 建立 PR(多種方式)
gh pr create # 互動模式
gh pr create --fill # 從提交記錄自動填入
gh pr create --draft # 建立為草稿
gh pr create --draft --fill # 草稿並自動填入
gh pr create -t "標題" -b "說明" -B main
gh pr create --label "review-needed" --assignee @me
# 列出 PR
gh pr list # 開放中的 PR
gh pr list --assignee @me # 您的 PR
gh pr list --search "review-requested:@me" # 要求您審查的 PR
gh pr list --draft # 僅顯示草稿 PR
# 檢視 PR 詳細資訊
gh pr view 45 # 在終端機檢視 PR
gh pr view 45 --web # 在瀏覽器中開啟
程式碼審查工作流程
# 在本地端簽出 PR 以進行測試
gh pr checkout 45 # 在本地端簽出 PR 分支
# 檢視變更內容
gh pr diff 45 # 檢視 PR 的差異
gh pr diff # 目前分支 PR 的差異
# 新增審查留言
gh pr comment 45 -b "LGTM,第 42 行有個小建議"
gh pr comment -b "請新增測試" # 對目前分支的 PR 留言
# 提交正式審查
gh pr review 45 --approve
gh pr review 45 --request-changes -b "請修正錯誤處理"
gh pr review 45 --comment -b "整體不錯,有幾點建議"
# 合併
gh pr merge 45 # 互動式合併
gh pr merge 45 --squash # 壓縮合併
gh pr merge 45 --rebase # 變基合併
gh pr merge 45 --merge # 標準合併提交
gh pr merge 45 --auto # 在檢查通過時自動合併
更新現有 PR
gh pr edit 45 --title "新標題"
gh pr edit 45 --body "已更新的說明"
gh pr edit 45 --base develop
gh pr edit 45 --add-label "ready-for-review"
gh pr ready 45 # 標記為就緒(移除草稿狀態)
GitHub Actions 工作流程管理
# 列出工作流程執行
gh run list # 最近的工作流程執行
gh run list --workflow=ci.yml # 特定工作流程
gh run list --status=failure # 僅顯示失敗的執行
# 檢視工作流程執行詳細資訊
gh run view # 互動式執行選擇器
gh run view 12345 # 特定執行
gh run view 12345 --web # 在瀏覽器中開啟
# 觸發工作流程
gh workflow run ci.yml # 在預設分支上執行
gh workflow run ci.yml --ref feature/x # 在特定分支上執行
gh workflow run ci.yml -f key=value # 帶入輸入參數
# 重新執行失敗的任務
gh run rerun 12345 # 重新執行所有任務
gh run rerun 12345 --failed # 僅重新執行失敗的任務
# 檢視任務日誌
gh run view 12345 --log # 完整日誌輸出
gh run view 12345 --log-failed # 僅失敗任務的日誌
# 監控進行中的執行
gh run watch # 監控目前執行
gh run watch 12345 # 監控特定執行
常見旗標參考
| 旗標 | 說明 |
|---|---|
-R, --repo OWNER/REPO | 指定不同的儲存庫 |
-B, --base | PR 的基礎分支 |
-H, --head | PR 的來源分支 |
-t, --title | 議題/PR 的標題 |
-b, --body | 議題/PR 的內文/說明 |
-l, --label | 標籤(以逗號分隔) |
-a, --assignee | 指派的使用者名稱 |
-m, --milestone | 里程碑名稱 |
--draft | 建立為草稿 PR |
--fill | 從提交訊息自動填入 |
--web | 在瀏覽器中開啟 |
-y, --yes | 跳過確認提示 |
環境變數
export GH_TOKEN="ghp_xxxx" # 個人存取權杖
export GH_HOST="github.example.com" # GitHub Enterprise 執行個體
export GH_REPO="owner/repo" # 預設儲存庫
提示與注意事項
使用 Markdown 的多行說明
當建立包含含 Markdown(程式碼區塊、反引號)的長篇說明的議題或 PR 時,請避免使用可能會因 shell 解譯而失敗的 heredoc。建議改用:
# 步驟 1:將說明寫入暫存檔案(在 bash 之外)
# 步驟 2:從暫存檔案建立
gh issue create -t "標題" -b "$(cat temp_description.txt)"
# 步驟 3:清理
rm temp_description.txt
這可以避免下列問題:
- 程式碼區塊中的反引號與命令替換衝突
- 特殊字元被 shell 解譯
- Heredoc 結束標記衝突
從現有檔案讀取說明
若要從 Markdown 計劃檔案建立議題或 PR:
# 使用 body-file 旗標以獲得基於檔案的乾淨說明
gh issue create -t "標題" --body-file docs/plans/my-plan.md
gh pr create -t "標題" --body-file docs/plans/my-plan.md
詳細參考
如需完整的命令選項與範例,請參閱 references/commands.md。