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

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

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

# 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

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

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

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

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

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

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

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

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

# 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

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

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

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

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

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

# 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)

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

# 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

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

gh release upload v1.0.0 ./dist/package.zip --clobber
gh release view v1.0.0 --json assets      # View attached assets

Manage Releases

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

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

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

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

9. Secrets & Variables

Repository Secrets

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

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

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

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

# 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

# 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

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

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

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

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

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

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

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

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

17. Gists

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

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

19. Environment Variables

20. Exit Codes

21. Common Workflows

Feature Development Flow

# 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

# 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

# 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

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

Batch Processing

# 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

# 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

# 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