github skill

GitHub

Use gh for GitHub. Use git for local commits/branches/push/pull. Use code-reading tools for deep reviews.

Auth

gh auth status
gh auth login

Gateway HOME can differ from operator HOME. If gh auth exists elsewhere, set GHCONFIGDIR in the gateway service env and restart.

PRs

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

When creating or refreshing a PR body, append this final footer only when the Runtime line supplies sessionUrl=. Replace with that URL verbatim; do not construct or modify it. sessionUrl is supplied only for an explicitly public session. Omit the footer when it is absent; never substitute a private chat URL or enable sharing to obtain one. Preserve any publication marker before exactly one footer, and keep the footer final:

---
[View the OpenClaw team session](<sessionUrl>)

URLs work directly: gh pr view https://github.com/owner/repo/pull/55.

Async merges

Use the repository's native landing workflow when provided. For authorized programmatic merges elsewhere, use GitHub's async merge API through gh api; gh pr merge does not select this API. Supply the reviewed head SHA, preserve required reviews/checks, and check stack membership first: submitting a stacked PR also merges or queues its open downstack PRs, which need their own review and authorization.

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'

Keep the Octopool guard header first after api. Protected older wrappers reject it before they can rewrite merge authority; use an Octopool build containing the async guard if it is refused. The supported wrapper preserves SHA/method/action/bypass and only rewrites commit text. Native gh can pass the header through. Do not remove it, disable policy, or select a raw binary to work around a rejection.

Retain details.uuid from a 202 response before polling. pending means wait; merged includes details.sha, which still needs final PR/head verification. enqueued means queued, not merged: monitor the PR itself. To honor a configured queue, use mergeaction=default (or mergequeue to explicitly enqueue), omitting direct-only method/title/message fields. Never enable bypass_rules without authorization.

On failed, report details.message. A 409 identifies an existing request; inspect its UUID and options without resubmitting. Lost replies, polling errors, and result expiry after 24 hours require reconciliation, never a blind retry or synchronous fallback. Poll with bounded waits and fresh reads. Async processing does not arm auto-merge for unmet checks; use the native workflow or gh pr merge --auto when that behavior is authorized.

Landing ownership

When the user asks to land or merge a PR, the terminal outcome is the PR's verified GitHub state, not the end of a review, worker turn, or CI observation.

proves state is MERGED.

• Keep the job active until gh pr view ... --json state,mergedAt,mergeCommit

continuation work when they are in scope. Patch them, rerun the required gates, and re-evaluate the exact updated head.

• Treat review findings, merge conflicts, failed checks, and requested changes as

wait or merge workflow; do not claim success from partial green checks.

• A pending check is a wait state, not completion. Use the repository's supported

continue the same session rather than treating its report as the final result.

• If work was delegated to a persistent session and that run stops before merge,

credentials, or a product decision that cannot be inferred safely. Report the exact blocker and leave the PR unmerged.

• Stop as blocked only when continuing requires new authority, unavailable

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/runs

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}'

Use --json + --jq for structured output. Use --body-file for comments/bodies containing backticks, shell snippets, env names, or user text.