7 added, 3 removed. Audit A to A.
---
name: github
description: Interact with GitHub (issues, PRs, repos, releases) using the `gh` CLI. Use when asked to read or write GitHub state — open an issue, fetch PR diff, comment, list runs, etc.
---
# github — GitHub via the `gh` CLI
The `gh` CLI is installed on PATH. The gateway environment provides a
`GITHUB_PAT` env var (a Team-Commonly fine-grained PAT with repo + PR scope)
which `gh` picks up automatically as `GH_TOKEN`.
The active GitHub identity is **Team-Commonly bot identity** — anything you
push, comment, or open will be attributed to that account.
> **No shell? Don't use `gh`.** The `gh` examples below assume a real shell
> (codex / claude-code runtimes). OpenClaw runtimes (theo/nova/pixel/ops) have
> **no shell** and cannot run `gh` at all. For those agents:
> - Read a PR diff: `web.fetch` the raw public diff at
> `https://patch-diff.githubusercontent.com/raw/Team-Commonly/commonly/pull/<N>.diff`.
> - Post a review verdict: write it into the dev pod chat (read-only review).
- > - codex / claude-code runtimes should instead use the `commonly_pr_diff` /
- > `commonly_pr_review` MCP tools, which read the diff and post the review
- > **onto the PR**.
+ > - codex / claude-code runtimes have a shell: use `gh` directly, as below.
+ >
+ > There is deliberately no `commonly_pr_*` MCP tool. The pair that existed was
+ > removed because it spent a shared server-side credential on a caller-chosen
+ > repository, so any agent could review any repo that credential reached. `gh`
+ > acts as the machine's own GitHub identity and supports line-level comments,
+ > which those tools never did.
## Common operations
### Issues
```bash
# List open issues in a repo
gh issue list --repo Team-Commonly/commonly --state open
# Create an issue
gh issue create --repo Team-Commonly/commonly \
--title "Title here" \
--body "Body here"
# Comment on an issue
gh issue comment 123 --repo Team-Commonly/commonly --body "comment"
```
### Pull requests
```bash
# List open PRs
gh pr list --repo Team-Commonly/commonly --state open
# View a PR (diff, comments, status)
gh pr view 287 --repo Team-Commonly/commonly --json title,body,additions,deletions
# Get a PR's diff
gh pr diff 287 --repo Team-Commonly/commonly
# Comment on a PR
gh pr comment 287 --repo Team-Commonly/commonly --body "comment text"
# Check CI status
gh pr checks 287 --repo Team-Commonly/commonly
```
### Repos / files
```bash
# View a file at a specific ref
gh api repos/Team-Commonly/commonly/contents/README.md --jq '.content' | base64 -d
# Search code
gh search code 'commonly_attach_file' --repo Team-Commonly/commonly --limit 20
```
### Workflows / runs
```bash
# List recent workflow runs
gh run list --repo Team-Commonly/commonly --limit 10
# View a specific run's logs
gh run view 12345 --repo Team-Commonly/commonly --log
```
## Heredoc for multi-line PR/issue bodies
```bash
gh pr comment 287 --repo Team-Commonly/commonly --body "$(cat <<'EOF'
Multi-line comment.
- Bullet one
- Bullet two
EOF
)"
```
## Useful patterns
- **Always pass `--repo <org/name>`** explicitly; the gateway's working
directory may not be inside a clone.
- **Prefer `--json <fields> --jq <expr>`** over scraping plain output —
more reliable and structured.
- **Don't push code directly** — the dev pattern is "open a PR with `gh pr
create --base main --head <branch>`" and let humans review.
## When NOT to use github
- For long-running coding tasks → delegate to `sam-local-codex` via DM
(per ADR-005 Stage 3).
- For pasting GitHub URLs into chat → just include the URL; the chat surface
renders it.