---
name: github
description: GitHub PRs, issues, reviews, releases, and repo operations via gh CLI
metadata:
  activation:
    keywords: [github, gh, gist, github actions]
    patterns:
      - "(?i)\\bgithub\\.com/[\\w-]+/[\\w-]+"
      - "(?i)\\bgh\\s+(pr|issue|release|repo|gist|search|run|api)\\b"
      - "(?i)\\b(create|open|list|show|close|merge|review)\\s+(\\w+\\s+)?(pr|pull\\s*request)s?\\b"
      - "(?i)\\b(create|open|list|show|close)\\s+(\\w+\\s+)?issues?\\b"
      - "(?i)\\bmy\\s+(pr|pull\\s*request|issue)s?\\b"
    context:
      git-remote: ["github\\.com"]
      files: [".github", ".github/workflows"]
  requires:
    bins: [gh]
  superseded-by:
    tools: [MCP_github]
---
## GitHub Operations

Use the `shell` tool with `gh` CLI commands. Output is JSON by default with `--json`.

### Authentication

```
gh auth status                         # check current auth
gh auth login                          # interactive login
```

### Pull Requests

Create:
```
gh pr create --title "feat: add X" --body "## Summary\n- ...\n\n## Test Plan\n- ..." --base main
gh pr create --fill                    # auto-fill from commits
gh pr create --draft                   # draft PR
gh pr create --reviewer user1,user2
```

List & View:
```
gh pr list --state open --json number,title,author,updatedAt
gh pr view {NUMBER} --json title,body,state,reviews,mergeable,statusCheckRollup
gh pr view {NUMBER} --comments        # show review comments
gh pr diff {NUMBER}                    # show diff
```

Review:
```
gh pr review {NUMBER} --approve
gh pr review {NUMBER} --request-changes --body "..."
gh pr review {NUMBER} --comment --body "..."
gh pr checks {NUMBER}                  # CI status
```

Merge & Close:
```
gh pr merge {NUMBER} --squash --delete-branch
gh pr merge {NUMBER} --merge           # merge commit
gh pr merge {NUMBER} --rebase
gh pr close {NUMBER}
```

### Issues

Create:
```
gh issue create --title "Bug: ..." --body "## Steps\n1. ...\n\n## Expected\n...\n\n## Actual\n..."
gh issue create --label bug,priority:high --assignee @me
```

List & View:
```
gh issue list --state open --json number,title,labels,assignees,updatedAt
gh issue list --label "bug" --assignee @me
gh issue view {NUMBER} --json title,body,state,comments
```

Update & Close:
```
gh issue close {NUMBER} --reason completed
gh issue edit {NUMBER} --add-label "in-progress" --add-assignee @me
gh issue comment {NUMBER} --body "Fixed in #456"
```

### Repo Operations

```
gh repo view --json name,description,defaultBranchRef
gh repo clone {OWNER}/{REPO}
gh repo fork {OWNER}/{REPO} --clone
```

### Releases

```
gh release list --json tagName,name,publishedAt
gh release view {TAG}
gh release create {TAG} --title "v1.0" --notes "## Changes\n- ..."
gh release create {TAG} --generate-notes    # auto-generate from commits
gh release upload {TAG} ./dist/*.tar.gz
```

### Gists

```
gh gist create {FILE} --public --desc "..."
gh gist list --json id,description,updatedAt
gh gist view {ID}
```

### Searches

```
gh search prs --repo {OWNER}/{REPO} --state open --json number,title
gh search issues --label "bug" --state open --json number,title,repository
gh search code "pattern" --repo {OWNER}/{REPO}
```

### Cross-Repo References

When given a GitHub URL, extract owner/repo/number:
```
# https://github.com/owner/repo/pull/123
gh pr view 123 --repo owner/repo --json title,body,state
# https://github.com/owner/repo/issues/456
gh issue view 456 --repo owner/repo --json title,body,state
```

### Guidelines
- Use `--json` fields to get structured output; pipe to `jq` for filtering
- Use `--jq` for inline filtering: `gh pr list --json number,title --jq '.[].title'`
- Link issues in PR body with `Fixes #123` or `Closes #456`
- Draft PRs for work-in-progress: `--draft`
- Read operations (list, view, search) are low-risk
- Write operations (create, edit, comment) are medium-risk — confirm with user
- Destructive operations (close, merge, delete-branch) are high-risk — always confirm
- Use `--repo owner/repo` for cross-repo operations
