GitHub

GitHub 是做什麼的？

使用 gh 處理 GitHub。使用 git 處理本地提交、分支、推送與拉取。使用程式碼閱讀工具進行深度審查。

驗證

gh auth status
gh auth login

Gateway 的 HOME 目錄可能與操作者的 HOME 目錄不同。如果 gh 的驗證資訊存在於其他地方，請在 gateway 服務環境中設定 GH_CONFIG_DIR 並重新啟動。

Pull Requests (PR)

gh pr list --repo owner/repo --json number,title,state,author,url
gh pr view 55 --repo owner/repo --json title,body,author,files,commits,reviews,reviewDecision
gh pr checks 55 --repo owner/repo
gh pr diff 55 --repo owner/repo
gh pr create --repo owner/repo --title "feat: title" --body-file /tmp/pr.md

在建立或更新 PR 說明時，僅在 Runtime 行提供了 sessionUrl=<exact-url> 時，才附加這個最終頁尾。將 <sessionUrl> 替換為該網址的精確內容；請勿自行建構或修改。當 sessionUrl 不存在時，請省略頁尾。請在剛好一個頁尾之前保留任何發布標記，並確保頁尾維持在最後：

---
[View the OpenClaw team session](https://raw.githubusercontent.com/clawdbot/clawdbot/main/<sessionUrl>)

URL 可以直接使用：gh pr view https://github.com/owner/repo/pull/55。

非同步合併

當儲存庫提供了原生的合併工作流程時，請使用它。對於其他地方需要授權的程式化合併，請透過 gh api 使用 GitHub 的非同步合併 API；gh pr merge 不會選用此 API。請提供已審查的 HEAD SHA，保留必要的審查與檢查，並先檢查堆疊歸屬：提交一個堆疊中的 PR 也會合併或排入其下方開啟的 PR，而這些 PR 需要它們自己的審查與授權。

gh api -H 'X-Octopool-Require: merge-async-v1' \
  --method PUT repos/owner/repo/pulls/55/merge-async \
  -H 'X-GitHub-Api-Version: 2026-03-10' \
  -f sha=REVIEWED_HEAD_SHA -f merge_method=squash -f merge_action=direct_merge
gh api -H 'X-Octopool-Require: merge-async-v1' \
  repos/owner/repo/pulls/55/merge-async/REQUEST_UUID \
  -H 'X-GitHub-Api-Version: 2026-03-10' -H 'Cache-Control: max-age=0'

請在 api 之後立即保留 Octopool 防護標頭。受保護的舊版包裝器會拒絕該標頭，以防止它們在重新寫入合併權限之前被處理；如果被拒絕，請使用包含非同步防護的 Octopool 構建版本。受支援的包裝器會保留 SHA、方法、動作與繞過設定，並且只會重寫提交文字。原生的 gh 可以傳遞此標頭。請勿為了繞過拒絕而移除它、停用政策或選擇原始二進位檔。

在輪詢之前，請從 202 回應中保留 details.uuid。pending 表示等待；merged 包含 details.sha，但仍需最終的 PR/HEAD 驗證。enqueued 表示已排入佇列，而非已合併：請監控 PR 本身。為了遵循已設定的佇列，請使用 merge_action=default（或明確使用 merge_queue 排入佇列），並省略僅限直接合併的 method、title 與 message 欄位。未經授權，切勿啟用 bypass_rules。

若狀態為 failed，請回報 details.message。409 狀態表示已存在請求；請檢查其 UUID 與選項，不要重新提交。遺失的回應、輪詢錯誤以及 24 小時後的結果過期均需進行協調，絕不能盲目重試或使用同步回退。請使用有限的等待時間進行輪詢，並讀取最新資料。非同步處理不會為未滿足的檢查啟用自動合併；當該行為獲得授權時，請使用原生工作流程或 gh pr merge --auto。

合併所有權

當使用者要求 landing 或合併一個 PR 時，最終結果必須是經驗證的 GitHub 狀態，而非審查、工作人員輪次或 CI 觀察的結束。

• 保持工作活躍，直到 gh pr view ... --json state,mergedAt,mergeCommit 證明 state 為 MERGED。
• 將審查結果、合併衝突、失敗的檢查與要求的變更視為範圍內的持續工作。修補它們，重新執行必要的閘道檢查，並重新評估確切的更新後 HEAD。
• 待處理的檢查是等待狀態，而非完成。請使用儲存庫支援的等待或合併工作流程；不要根據部分通過的綠色檢查就宣稱成功。
• 如果工作已委派給持久化 session，並且該 session 在合併前停止，請繼續同一個 session，而不是將其報告視為最終結果。
• 只有在繼續需要新的授權、無效的憑證或無法安全推斷的產品決策時，才將狀態視為受阻而停止。請回報確切的阻礙因素，並將 PR 保留為未合併狀態。

Issues

gh issue list --repo owner/repo --state open --json number,title,labels,url
gh issue view 42 --repo owner/repo --json title,body,comments,labels,state
gh issue create --repo owner/repo --title "Bug: ..." --body-file /tmp/issue.md
gh issue comment 42 --repo owner/repo --body-file /tmp/comment.md
gh issue close 42 --repo owner/repo --comment "Fixed in ..."

CI / 執行

gh run list --repo owner/repo --limit 10
gh run view <run-id> --repo owner/repo --json status,conclusion,headSha,url
gh run view <run-id> --repo owner/repo --log-failed
gh run rerun <run-id> --repo owner/repo --failed

API

gh api repos/owner/repo/pulls/55 --jq '.title, .state, .user.login'
gh api repos/owner/repo/labels --jq '.[].name'
gh api --cache 1h repos/owner/repo --jq '{stars: .stargazers_count, forks: .forks_count}'

請使用 --json 搭配 --jq 來取得結構化輸出。請使用 --body-file 來處理包含反引號、shell 程式碼片段、環境變數名稱或用戶文字的評論或說明。