---
name: "GitHub CLI (gh)"
description: "Skill for GitHub CLI (gh) — auto-generated from documentation"
version: "1.0.0"
author: "skynet"
category: "dev"
agents: ["claude-code", "codex", "gemini"]
tags: ["github-cli", "dev", "auto-generated"]
---

# GitHub CLI (gh)

---
name: GitHub CLI (gh)
description: Use when you need to interact with GitHub repositories, issues, pull requests, and workflows directly from the command line. Essential for automated workflows, CI/CD pipelines, and efficient Git-based development processes.
metadata:
  author: skynet
  version: 1.0.0
category: dev
---

# GitHub CLI (gh) Skill

## Authentication & Setup

```bash
# Login to GitHub
gh auth login

# Check authentication status
gh auth status

# Set up Git protocol preference
gh config set git_protocol ssh
gh config set git_protocol https
```

## Repository Operations

### Creating & Cloning
```bash
# Create new repository
gh repo create my-project --public --clone
gh repo create my-project --private --description "My project description"

# Clone repository
gh repo clone owner/repository
gh repo clone owner/repository ./custom-directory

# Fork repository
gh repo fork owner/repository --clone
gh repo fork owner/repository --remote
```

### Repository Management
```bash
# View repository info
gh repo view
gh repo view owner/repository

# List repositories
gh repo list
gh repo list owner --limit 50

# Delete repository
gh repo delete owner/repository --confirm
```

## Issue Management

### Creating & Listing Issues
```bash
# Create new issue
gh issue create --title "Bug report" --body "Description of the bug"
gh issue create --title "Feature request" --assignee @me --label enhancement

# List issues
gh issue list
gh issue list --state open --assignee @me
gh issue list --label bug --limit 10

# View issue details
gh issue view 123
gh issue view 123 --comments
```

### Issue Operations
```bash
# Close issue
gh issue close 123 --comment "Fixed in latest commit"

# Reopen issue
gh issue reopen 123

# Edit issue
gh issue edit 123 --title "New title" --add-label priority
gh issue edit 123 --remove-assignee @user

# Pin/unpin issue
gh issue pin 123
gh issue unpin 123
```

## Pull Request Workflows

### Creating Pull Requests
```bash
# Create PR from current branch
gh pr create --title "Add new feature" --body "Description of changes"
gh pr create --draft --assignee @me --reviewer @teammate

# Create PR with template
gh pr create --template bug_report.md

# Create PR to specific branch
gh pr create --base develop --head feature-branch
```

### PR Management
```bash
# List pull requests
gh pr list
gh pr list --state merged --limit 20
gh pr list --author @me --label "needs review"

# View PR details
gh pr view 456
gh pr view 456 --comments

# Checkout PR locally
gh pr checkout 456

# Review PR
gh pr review 456 --approve
gh pr review 456 --request-changes --body "Please fix the tests"
gh pr review 456 --comment --body "LGTM!"
```

### PR Operations
```bash
# Merge pull request
gh pr merge 456 --merge --delete-branch
gh pr merge 456 --squash --body "Summary of changes"
gh pr merge 456 --rebase

# Close PR without merging
gh pr close 456 --comment "No longer needed"

# Mark PR as ready for review
gh pr ready 456

# Convert to draft
gh pr edit 456 --draft
```

## GitHub Actions & Workflows

```bash
# List workflow runs
gh run list
gh run list --workflow ci.yml --limit 10

# View workflow run details
gh run view 123456789

# Re-run failed workflow
gh run rerun 123456789 --failed

# Cancel running workflow
gh run cancel 123456789

# Watch workflow run in real-time
gh run watch 123456789

# Download workflow artifacts
gh run download 123456789
```

## Release Management

```bash
# Create release
gh release create v1.0.0 --title "Version 1.0.0" --notes "Release notes"
gh release create v1.0.0 ./dist/* --prerelease

# List releases
gh release list --limit 10

# View release details
gh release view v1.0.0

# Upload additional assets
gh release upload v1.0.0 ./binary.tar.gz

# Delete release
gh release delete v1.0.0 --yes
```

## Decision Tree: When to Use Which Command

```
Need to work with GitHub?
├─ Repository tasks?
│  ├─ Creating new repo → gh repo create
│  ├─ Forking existing → gh repo fork
│  └─ Getting info → gh repo view
├─ Issue tracking?
│  ├─ Reporting bug → gh issue create --label bug
│  ├─ Feature request → gh issue create --label enhancement
│  └─ Managing existing → gh issue list/edit/close
├─ Code review process?
│  ├─ Submitting changes → gh pr create
│  ├─ Reviewing code → gh pr review
│  └─ Merging approved → gh pr merge
└─ CI/CD monitoring?
   ├─ Check workflow status → gh run list
   ├─ Debug failures → gh run view
   └─ Re-run builds → gh run rerun
```

## Advanced Workflows

### Bulk Operations
```bash
# Close multiple issues
gh issue list --state open --json number --jq '.[].number' | \
  xargs -I {} gh issue close {}

# Approve multiple PRs from trusted contributor
gh pr list --author trusted-dev --json number --jq '.[].number' | \
  xargs -I {} gh pr review {} --approve
```

### Scripting with gh
```bash
#!/bin/bash
# Auto-create PR when pushing to feature branch
if [[ $(git branch --show-current) == feature/* ]]; then
  gh pr create --draft --title "WIP: $(git branch --show-current)" \
    --body "Auto-created PR for feature branch"
fi
```

### API Integration
```bash
# Make custom API calls
gh api repos/:owner/:repo/issues --field state=open
gh api user --jq '.login'

# Pagination
gh api repos/:owner/:repo/issues --paginate --field state=all
```

## Troubleshooting

### Authentication Issues
```
Error: HTTP 401: Bad credentials
```
**Fix:** Re-authenticate with `gh auth login` and ensure token has correct scopes

### Permission Errors
```
Error: HTTP 403: Resource not accessible by integration
```
**Fix:** Check repository permissions and token scopes:
```bash
gh auth status
gh repo view owner/repo  # Verify access
```

### Network/API Issues
```
Error: failed to run git: exit status 128
```
**Fix:** Verify Git configuration and repository URL:
```bash
gh auth setup-git
git remote -v
```

### Large File Uploads
```
Error: file too large
```
**Fix:** Use release assets for large files:
```bash
gh release create v1.0.0
gh release upload v1.0.0 large-file.zip
```

### Workflow Run Failures
```bash
# Debug workflow issues
gh run view 123456789 --log
gh run list --workflow broken.yml --json conclusion
```

## Configuration & Customization

```bash
# Set default editor
gh config set editor vim

# Configure default repository visibility
gh config set prompt disabled

# Set aliases
gh alias set co 'pr checkout'
gh alias set pv 'pr view'

# List all configuration
gh config list
```

## Integration Examples

### Git Hooks Integration
```bash
# In .git/hooks/post-push
#!/bin/bash
gh pr create --draft 2>/dev/null || echo "PR might already exist"
```

### CI/CD Pipeline Usage
```bash
# In GitHub Actions workflow
- name: Create release
  run: gh release create ${{ github.ref_name }} --generate-notes
  env:
    GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
```