---
name: "GitHub"
description: Work with GitHub repos, issues, pull requests, Actions, and releases through the official `gh` CLI.
version: 1
situations: github, repos, pull requests, issues, code review, ci
requires-secrets:
requires-packages:
requires-connector: github
---

# GitHub (`gh`)

Everything here runs through the official GitHub CLI in your **bash** tool. The operator connected the
account from 00's skill store, so `gh` is already authenticated — you never handle a token.

## First, know who you are

```
gh auth status
```

If that says you are not logged in, stop and tell the operator to open **Skill store → GitHub →
Connect**. Do not try to log in yourself; the login is an interactive browser flow that only the
operator can complete.

## Read

```
gh repo view OWNER/REPO --json name,description,defaultBranchRef,stargazerCount
gh issue list --repo OWNER/REPO --state open --limit 30 --json number,title,labels,assignees,updatedAt
gh pr list --repo OWNER/REPO --state open --json number,title,author,isDraft,reviewDecision
gh pr view 123 --repo OWNER/REPO --json title,body,files,comments
gh pr diff 123 --repo OWNER/REPO
gh run list --repo OWNER/REPO --limit 10 --json status,conclusion,name,headBranch
gh search issues "is:open label:bug org:ORG" --limit 30 --json number,title,repository
```

Always pass `--json <fields>` when you plan to parse the output — the human-readable format is a
table that changes shape. Add `--jq '.[] | .title'` to filter without a second tool.

## Write

These change something someone else can see. Say what you are about to do, in one line, before you do
it — and if the request was ambiguous about *which* repo or branch, ask first.

```
gh issue create --repo OWNER/REPO --title "…" --body "…" --label bug
gh issue comment 123 --repo OWNER/REPO --body "…"
gh pr create --repo OWNER/REPO --base main --head my-branch --title "…" --body "…"
gh pr comment 123 --repo OWNER/REPO --body "…"
gh release create v1.2.3 --repo OWNER/REPO --notes "…"
```

## Never without being asked in this turn

`gh pr merge`, `gh repo delete`, `gh release delete`, `gh run cancel`, force-pushes, and anything
that rewrites history. Merging a pull request is a decision, not a step.

## Notes

- The connected account's own permissions apply. A 404 on a repo you know exists usually means the
  token's scopes don't cover it — report that rather than retrying.
- `gh api` reaches anything the CLI doesn't wrap: `gh api repos/OWNER/REPO/commits --paginate`.
- Rate limits: `gh api rate_limit`. If you're being throttled, say so instead of looping.