github

SKILL.md

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 GH_CONFIG_DIR 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=<exact-url>. Replace <sessionUrl> with that URL verbatim; do not construct or modify it. Omit the footer when sessionUrl is absent. 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 merge_action=default (or merge_queue 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.

Keep the job active until gh pr view ... --json state,mergedAt,mergeCommit
proves state is MERGED.

Treat review findings, merge conflicts, failed checks, and requested changes as
continuation work when they are in scope. Patch them, rerun the required gates,
and re-evaluate the exact updated head.

A pending check is a wait state, not completion. Use the repository's supported
wait or merge workflow; do not claim success from partial green checks.

If work was delegated to a persistent session and that run stops before merge,
continue the same session rather than treating its report as the final result.

Stop as blocked only when continuing requires new authority, unavailable
credentials, or a product decision that cannot be inferred safely. Report the
exact blocker and leave the PR unmerged.

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.