---
name: gh-cli
description: Master the GitHub CLI (gh) for complete Software Development Lifecycle management. Use this skill when managing GitHub repositories, issues, pull requests, GitHub Projects, releases, Actions workflows, secrets, Pages deployments, wikis, Codespaces, and automating via the GitHub API. Covers the entire SDLC from terminal without browser interaction.
trigger: When the user wants to use the gh CLI to manage repositories, issues, pull requests, projects, releases, Actions, secrets, GitHub Pages, search code/repos, manage Codespaces, fork workflows, create releases, manage labels/milestones, or make authenticated GitHub API calls. Triggers on phrases like "gh issue", "gh pr", "gh repo", "github cli", "GitHub CLI", "gh actions", "gh release", "gh secret", "gh api".
version: 1.0.0
tags: [github, cli, sdlc, devops, automation, github-actions, issues, pull-requests, repos, projects, releases, pages, secrets, codespaces, api]
authors: [jasondeland]
inputs:
  repository: "Full 'owner/repo' name — required for most commands"
  issue_number: "Numeric issue number for view/edit operations"
  pr_number: "Numeric PR number for review/merge operations"
  project_number: "GitHub Project v2 number for --owner or --repo scope"
  workflow_name: "Name of a GitHub Actions workflow file (e.g. 'build.yml')"
  secret_name: "Name of the secret/variable to create/delete"
  release_tag: "Git tag for release operations (e.g. 'v1.0.0')"
  api_endpoint: "GitHub REST or GraphQL API endpoint path"
  search_query: "GitHub search syntax query string"
  branch_name: "Branch name for checkout, push, or PR creation"
  label_name: "Label name for filtering or applying"
  milestone_title: "Milestone title for grouping issues"
  gh_flags: "Additional gh flags like --json, --web, --jq, --paginate, --limit"
outputs:
  cli_command: "Complete gh CLI command ready to execute"
  workflow_script: "Shell script combining gh commands for automation"
  api_request: "Formatted gh api command with appropriate flags and jq filters"
  json_data: "Structured JSON output from --json gh commands"
  formatted_output: "Human-readable formatted output using --jq"
---

# GitHub CLI (gh) — Complete SDLC Skill

> **Purpose**: Complete GitHub project management from terminal — repos, issues, PRs, projects, releases, Actions, secrets, Pages, and API.

---

## Quick Reference

```bash
gh --version                    # Check version (currently 2.83.2)
gh auth status                 # Show current authentication state
gh help <command>              # Get help for any command
gh <command> --help            # Alternative help syntax
```

---

## 1. Authentication

### Login & Authentication
```bash
gh auth login                      # Interactive login flow
gh auth login --hostname github.com --git-protocol https
gh auth refresh                    # Refresh expired tokens
gh auth logout --hostname github.com
gh auth token                     # Print current auth token
```

### SSH Keys & GPG
```bash
# SSH Keys
gh ssh-key add ~/.ssh/id_ed25519.pub --title "Work Laptop"
gh ssh-key list

# GPG Keys
gh gpg-key list
gh gpg-key add /path/to/key.gpg
```

### Configuration
```bash
gh config get default_branch      # View setting
gh config set default_branch main # Set default branch
gh config list                    # List all config
```

---

## 2. Repository Management

### Create & Clone
```bash
gh repo create                    # Interactive create
gh repo create owner/repo --public --clone
gh repo create owner/repo --private --gitignore Ruby --license MIT --clone
gh repo clone owner/repo          # Clone via gh (handles auth automatically)
gh repo clone owner/repo path     # Clone to specific path
```

### Repo Operations
```bash
gh repo view                      # View current repo in terminal
gh repo view owner/repo           # View specific repo
gh repo view owner/repo --web     # Open in browser
gh repo edit --enable-delete-branch --delete-branch-on-close
gh repo archive owner/repo
gh repo sync owner/repo           # Sync from parent
```

### Fork Management
```bash
gh repo fork owner/repo           # Fork a repo
gh repo fork owner/repo --clone   # Fork and clone locally
gh repo fork owner/repo -- --no-fetch .  # Fork into current directory
```

### Collaborators
```bash
gh repo collaborator add owner/repo username --permission push
gh repo collaborator list owner/repo
gh repo collaborator remove owner/repo username
```

---

## 3. Issues — Full Lifecycle

### Create Issues
```bash
gh issue create                           # Interactive mode
gh issue create --title "Bug in auth" --body "Description..."
gh issue create --label bug --label "priority:high"
gh issue create --assignee @me
gh issue create --project "Roadmap"       # Add to project
gh issue create --milestone "v1.0"       # Assign milestone
```

### List & Search Issues
```bash
gh issue list                            # List open issues
gh issue list --state closed --limit 50
gh issue list --label bug --label "help wanted"
gh issue list --assignee @me
gh issue list --author owner
gh issue list --search "is:issue is:open assignees:@me"
```

### View & Manage Issues
```bash
gh issue view 123                        # View issue in terminal
gh issue view 123 --web                  # Open in browser
gh issue view 123 --comments             # Include comments
gh issue edit 123 --title "New title"
gh issue edit 123 --add-label "confirmed"
gh issue edit 123 --remove-label "needs-review"
gh issue edit 123 --add-assignee username
gh issue close 123
gh issue reopen 123
gh issue transfer 123 --destination-owner/destination-repo
```

### Bulk Operations
```bash
# Close all issues matching query
gh issue list --label "duplicate" --state open --json number | jq -r '.[].number' | xargs -I {} gh issue close {}

# Add labels to multiple issues
gh issue list --milestone "v1.0" --json number | jq -r '.[].number' | xargs -I {} gh issue edit {} --add-label "ready-for-release"
```

---

## 4. Pull Requests — Full Lifecycle

### Create PRs
```bash
gh pr create                              # Interactive mode
gh pr create --title "Feature description"
gh pr create --body "## What\n- Added feature X\n- Fixed bug Y"
gh pr create --label feature --label "needs-review"
gh pr create --assignee @me
gh pr create --reviewer owner/team       # Request team review
gh pr create --project "Roadmap"          # Add to project
gh pr create --milestone "v1.0"
gh pr create --draft                     # Create as draft
gh pr create --base main                 # Target branch
```

### List & Search PRs
```bash
gh pr list                               # List open PRs
gh pr list --state closed --limit 100
gh pr list --state merged
gh pr list --label "ready-for-review" --assignee @me
gh pr list --search "is:pr is:open author:@me"
gh pr list --head owner:feature-branch   # PRs from fork
```

### View & Manage PRs
```bash
gh pr view 456                            # View PR in terminal
gh pr view 456 --web                      # Open in browser
gh pr view 456 --comments                 # Include comments
gh pr diff 456                            # Show changes
gh pr check 456                           # Show CI status
gh pr status                              # Show PR status for current repo
```

### Review & Merge
```bash
gh pr review 456                          # Interactive review
gh pr review 456 --approve                # Approve
gh pr review 456 --request-changes --comment "Needs fixes"
gh pr merge 456                           # Interactive merge
gh pr merge 456 --squash --delete-branch  # Squash and merge
gh pr merge 456 --rebase --delete-branch  # Rebase and merge
gh pr merge 456 --admin --auto           # Auto-merge if checks pass
gh pr merge 456 --disable-auto           # Disable auto-merge
gh pr ready 456                          # Mark draft as ready
gh pr close 456                           # Close without merge
```

---

## 5. GitHub Projects (v2)

> **Note**: GitHub Projects v2 is different from Projects (classic). Use `gh project` for v2.

### List & View Projects
```bash
gh project list                           # List projects in org/account
gh project list --owner myorg
gh project view 1                         # View project by number
gh project view 1 --web                   # Open in browser
gh project view 1 --json fields,items     # JSON output
```

### Manage Project Items
```bash
# Add issue/PR to project
gh project item-add 1 --issue 123
gh project item-add 1 --pull-request 456

# Add project to repo (enables project visibility in repo)
gh repo edit --add-project "Project Name"

# Move items between columns (using item id and field value)
gh project item-move 1 --field Status --option "In Progress"
```

### Project Items (v2)
```bash
gh project item-list 1                    # List all items
gh project item-add 1 --issue 123         # Add issue
gh project item-add 1 --pull-request 456 # Add PR
gh project item-delete 1 ITEM-ID          # Remove item
```

---

## 6. GitHub Pages

### Pages Management
```bash
# Enable Pages (requires admin access)
gh api repos/owner/repo -XPATCH -f pages_build_type="workflow"

# View Pages status
gh api repos/owner/repo/pages

# Get Pages build log
gh api repos/owner/repo/pages/builds/latest
```

---

## 7. Releases

### Create Releases
```bash
gh release create                          # Interactive create
gh release create v1.0.0 --title "v1.0.0 Release"
gh release create v1.0.0 --notes "Bug fixes and improvements"
gh release create v1.0.0 --draft          # Create as draft
gh release create v1.0.0 --prerelease     # Mark as pre-release
gh release create v1.0.0 --target main     # Release from specific branch
```

### Attach Assets to Releases
```bash
gh release upload v1.0.0 ./dist/package.zip --clobber
gh release view v1.0.0 --json assets      # View attached assets
```

### Manage Releases
```bash
gh release list --limit 20
gh release delete v1.0.0 --yes
gh release edit v1.0.0 --title "Updated Title"
gh release edit v1.0.0 --add-tag v1.0.1   # Retag release
```

---

## 8. GitHub Actions

### Workflow Management
```bash
gh workflow list
gh workflow view 12345                    # View workflow run
gh workflow view 12345 --job job-id       # View specific job
gh workflow run build.yml                 # Trigger workflow
gh workflow run build.yml --ref feature-branch --param environment=staging
gh workflow enable 12345
gh workflow disable 12345
```

### Run Management
```bash
gh run list                               # List recent runs
gh run list --workflow build.yml
gh run list --status in_progress
gh run view 12345                         # View run details
gh run watch 12345                        # Watch live output
gh run download 12345                     # Download artifacts
gh run cancel 12345
gh run rerun 12345
gh run delete 12345
```

### Artifacts
```bash
gh run download 12345 --dir ./artifacts   # Download to directory
gh run download 12345 --name "test-results" --pattern "**/*.xml"
```

---

## 9. Secrets & Variables

### Repository Secrets
```bash
gh secret list                             # List all secrets
gh secret set MY_SECRET --body "value"    # Set secret
gh secret set MY_SECRET < secret.txt      # Set from file
gh secret set MY_SECRET --env production  # Environment-specific
gh secret delete MY_SECRET
gh secret set DEPLOY_KEY --app actions    # For Actions
```

### Organization Secrets
```bash
gh secret list --org myorg
gh secret set ORG_SECRET --org myorg --visibility all
gh secret set ORG_SECRET --org myorg --visibility private
gh secret set ORG_SECRET --org myorg --visibility selected --repos "repo1,repo2"
```

### Variables
```bash
gh variable list
gh variable set CI_COMMIT_SHA --body "$GITHUB_SHA"
gh variable set NODE_ENV --value production
gh variable delete NODE_ENV
```

---

## 10. API & Scripting

### Authenticated API Requests
```bash
gh api repos                               # GET request
gh api repos/owner/repo/issues --jq '.[] | {number,title,state}'
gh api repos/owner/repo/issues --state closed --method GET
gh api graphql --field query='{viewer {login}}'

# Paginated requests
gh api repos/owner/repo/issues --paginate

# Custom headers
gh api -H "Accept: application/vnd.github+json" /repos
```

### GraphQL Examples
```bash
# Query projects
gh api graphql -f query='
  query {
    viewer {
      login
      projectV2(number: 1) {
        title
        items(first: 10) {
          nodes {
            id
            fieldValues(first: 10) {
              nodes {
                ... on ProjectV2ItemFieldTextValue {
                  text
                }
              }
            }
          }
        }
      }
    }
  }
'
```

### JSON & jq Integration
```bash
# Export data
gh issue list --json number,title,labels --jq '.[] | "\(.number) \(.title)"'

# Count items
gh issue list --json number --jq 'length'

# Filter by label
gh issue list --json title,labels --jq '.[] | select(.labels[].name == "bug")'
```

---

## 11. Search

### Repository Search
```bash
gh search repos "language:python stars:>100"
gh search repos "user:owner pushed:>2024-01-01"
gh search repos --sort stars --order desc "machine learning"
```

### Issue & PR Search
```bash
gh search issues "repo:owner/repo is:issue label:bug"
gh search issues "author:username created:>2024-01-01"
gh search prs "repo:owner/repo state:open review:approved"
gh search issues "assignee:@me is:open"
```

---

## 12. Codespaces

### Manage Codespaces
```bash
gh codespace list                          # List codespaces
gh codespace create --repo owner/repo
gh codespace create --repo owner/repo --branch feature
gh codespace ssh codespace_name           # SSH into codespace
gh codespace stop codespace_name
gh codespace delete codespace_name
gh codespace ports list codespace_name     # List forwarded ports
```

---

## 13. Labels & Milestones

### Labels
```bash
gh label list
gh label create "priority:high" --color FF0000 --description "High priority"
gh label edit "priority:high" --color F00
gh label delete "wontfix"
# Clone labels from another repo
gh label clone owner/repo
```

### Milestones
```bash
gh milestone list
gh milestone create "v1.0" --due-date 2024-12-31
gh milestone edit "v1.0" --title "v1.0 Release"
gh milestone close "v1.0"
gh milestone delete "v1.0"
```

---

## 14. Extensions

### Install & Manage Extensions
```bash
gh extension list                           # List installed
gh extension install hub                     # Install community extension
gh extension install pr-lint               # Install PR linting
gh extension remove hub
gh extension upgrade --all
```

---

## 15. Aliases

```bash
gh alias set co "pr checkout"              # Create alias
gh alias set issues "issue list --author @me"
gh alias list                              # List all aliases
gh alias delete co                          # Delete alias
```

---

## 16. Status & Notifications

```bash
gh status                                  # Show your open items
gh status --show-prs                       # Include PRs
gh api notifications                       # List notifications
```

---

## 17. Gists

```bash
gh gist list                               # List your gists
gh gist create file.txt                    # Create from file
gh gist create --public file.txt           # Public gist
gh gist create --description "My gist" file.txt
gh gist view gist_id
gh gist edit gist_id --add file2.txt
gh gist delete gist_id
```

---

## 18. Rulesets

```bash
gh ruleset list                            # List rulesets
gh ruleset view 12345                       # View ruleset details
```

---

## 19. Environment Variables

| Variable | Description |
|----------|-------------|
| `GH_TOKEN` | GitHub token (alternative to `gh auth login`) |
| `GH_HOST` | GitHub Enterprise Server hostname |
| `GH_EDITOR` | Editor to use |
| `GH_PAGER` | Pager program |
| `GH_CONFIG_DIR` | Config directory |
| `GITHUB_TOKEN` | Token for Actions |
| `GH_REPO` | Default repository |

---

## 20. Exit Codes

| Code | Meaning |
|------|---------|
| 0 | Success |
| 1 | Error |
| 2 | Client error (malformed command) |
| 4 | Not Found |
| 8 | Conflict |
| 32 | State conflict |

---

## 21. Common Workflows

### Feature Development Flow
```bash
# 1. Fork and clone
gh repo fork owner/repo --clone
cd repo

# 2. Create feature branch
git checkout -b feature/new-feature

# 3. Make changes and commit
git add . && git commit -m "Add new feature"

# 4. Push and create PR
git push -u origin feature/new-feature
gh pr create --title "Add new feature" --reviewer owner/team

# 5. After approval, merge
gh pr review 123 --approve
gh pr merge 123 --squash --delete-branch

# 6. Sync latest
git checkout main && git pull
```

### Release Process
```bash
# 1. Create milestone for release
gh milestone create "v1.0"

# 2. Ensure all issues are in milestone
gh issue list --label "ready-for-release" | xargs -I {} gh issue edit {} --milestone "v1.0"

# 3. Close milestone
gh milestone close "v1.0"

# 4. Create release
git tag v1.0
git push origin v1.0
gh release create v1.0 --title "v1.0 Release" --generate-notes

# 5. Create GitHub Pages deployment (if applicable)
gh api repos/owner/repo -XPATCH -f build_type=workflow
```

### Project Management Flow
```bash
# 1. Create project
gh project create "Q1 Roadmap" --owner myorg --template Roadmap

# 2. Add issues to project
gh issue create --title "Feature A" --project "Q1 Roadmap"
gh issue create --title "Feature B" --project "Q1 Roadmap"

# 3. Update project status
gh project item-move ITEM-ID --field Status --option "In Progress"

# 4. Close completed items
gh issue close 123
```

---

## 22. Tips & Tricks

### Pretty Output
```bash
gh pr view 123 --json title,state,url,reviews --jq '. | "PR #\(.number): \(.title) (\(.state))"'
```

### Batch Processing
```bash
# Close all merged PRs
gh pr list --state merged --json number --jq '.[].number' | xargs -I {} gh pr close {}

# Archive old issues
gh issue list --state open --created=<2023-01-01 --json number | jq -r '.[].number' | xargs -I {} gh issue close {}
```

### Automation in CI/CD
```bash
# In GitHub Actions
gh workflow run tests.yml --ref $GITHUB_REF
gh run watch $(gh run list --json databaseId --jq '.[0].databaseId')
```

---

## Quick Command Reference

```bash
# Authentication
gh auth login    gh auth logout    gh auth status    gh auth refresh

# Repositories
gh repo create    gh repo clone    gh repo view    gh repo edit    gh repo fork    gh repo sync

# Issues
gh issue create    gh issue list    gh issue view    gh issue edit    gh issue close    gh issue reopen

# Pull Requests
gh pr create    gh pr list    gh pr view    gh pr edit    gh pr merge    gh pr close    gh pr review

# Projects
gh project list    gh project view    gh project item-add    gh project item-move

# Releases
gh release create    gh release list    gh release view    gh release delete

# Actions
gh workflow list    gh run list    gh run view    gh run watch    gh run rerun

# Secrets & Variables
gh secret list    gh secret set    gh secret delete    gh variable list

# Search & API
gh search repos    gh search issues    gh api

# Utilities
gh alias    gh config    gh help
```