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

GH_TOKEN

gh auth login

GH_HOST

GH_EDITOR

GH_PAGER

GH_CONFIG_DIR

GITHUB_TOKEN

GH_REPO

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