Github Cli

GitHub CLI Skill

Provides patterns for the gh CLI to interact with GitHub repositories, services, and APIs directly from the terminal. Covers authentication, repository management, issues, pull requests, actions, releases, projects, search, and the REST/GraphQL API. Git workflow patterns (branching, commits, CI/CD) are handled by a separate skill.

Quick Reference

Common Workflows

Output Formatting

Most gh list and view commands support structured output for scripting and automation.

Scoping: Repo, Env, Org

Secrets and variables can be scoped to different levels.

Project commands always require --owner @me or --owner org-name.

Authentication Prerequisites

The gh CLI requires authentication before most commands work. Run gh auth status to verify the current session. Missing scopes cause silent failures -- use gh auth refresh -s scope to add scopes without re-authenticating. For CI environments, set the GITHUB_TOKEN or GH_TOKEN environment variable instead of interactive login.

Common Mistakes

Delegation

• Search across repositories for code patterns or issues: Use Explore agent with gh search code and gh search issues
• Automate multi-step release workflows: Use Task agent to coordinate branch creation, PR merge, and release publishing
• Plan repository structure and access controls: Use Plan agent to design team permissions, branch protection, and workflow architecture

References

• Repos & Auth -- Authentication, repository management, configuration, extensions, aliases
• Issues -- Issue CRUD, labels, assignments, pinning, transferring, development branches
• Pull Requests -- PR creation, review, merge, checkout, checks, diff, auto-merge
• Actions -- Workflow runs, manual triggers, secrets, variables, caches, artifact downloads
• Releases & Search -- Releases, attestation verification, search, gists, SSH/GPG keys
• Projects & API -- Projects v2 management, REST API, GraphQL API, rulesets, status

Actions (CI/CD)

Workflow Runs

List Runs

gh run list
gh run list --workflow deploy.yml
gh run list --branch main --limit 10
gh run list --status failure
gh run list --user @me
gh run list --event push
gh run list --commit abc1234
gh run list --json databaseId,status,conclusion,headBranch

View Run Details

gh run view 12345
gh run view 12345 --web
gh run view 12345 --json jobs
gh run view 12345 --verbose
gh run view 12345 --log
gh run view 12345 --log-failed
gh run view 12345 --job 67890
gh run view 12345 --attempt 2
gh run view 12345 --exit-status

Watch a Run

gh run watch 12345
gh run watch 12345 --exit-status
gh run watch 12345 --interval 5
gh run watch 12345 --compact

Rerun

gh run rerun 12345
gh run rerun 12345 --failed
gh run rerun 12345 --job 67890
gh run rerun 12345 --debug

Cancel and Delete

gh run cancel 12345
gh run cancel 12345 --force
gh run delete 12345

Download Artifacts

gh run download 12345
gh run download 12345 --name "build-output"
gh run download 12345 --pattern "*.zip"
gh run download 12345 --dir ./artifacts

Workflows

List and View

gh workflow list
gh workflow list --all
gh workflow view deploy.yml
gh workflow view deploy.yml --web

Trigger a Workflow

gh workflow run deploy.yml
gh workflow run deploy.yml -f environment=production
gh workflow run deploy.yml -f environment=staging -f version=1.2.3
gh workflow run deploy.yml --ref feature-branch

Enable and Disable

gh workflow disable deploy.yml
gh workflow enable deploy.yml

Secrets

gh secret list
gh secret list --json name,updatedAt
gh secret set MY_SECRET
gh secret set MY_SECRET --body "secret-value"
gh secret set MY_SECRET < secret.txt
gh secret set MY_SECRET --env production
gh secret set MY_SECRET --org my-org --visibility all
gh secret delete MY_SECRET
gh secret delete MY_SECRET --env production

Key flags for gh secret set:

• --env -- set an environment-level secret
• --org -- set an organization-level secret
• --visibility -- organization secret visibility: all, private, selected
• --repos -- list of repositories for selected visibility

Variables

gh variable list
gh variable list --json name,value
gh variable get MY_VAR
gh variable set MY_VAR --body "value"
gh variable set MY_VAR --env production --body "prod-value"
gh variable set MY_VAR --org my-org --visibility all --body "org-value"
gh variable delete MY_VAR

Cache Management

gh cache list
gh cache list --json id,key,sizeInBytes
gh cache list --limit 50
gh cache delete cache-key-or-id
gh cache delete --all

Check CI Status

For the current PR:

gh pr checks
gh pr checks --watch
gh pr checks --json name,state,conclusion
gh run watch

Issues

List and Filter

gh issue list
gh issue list --state closed
gh issue list --label "bug" --assignee @me
gh issue list --milestone "v2.0"
gh issue list --search "memory leak in:title"
gh issue list --limit 50
gh issue list --json number,title,state,labels

View

gh issue view 123
gh issue view 123 --web
gh issue view 123 --json title,body,comments
gh issue view 123 --comments

Create

gh issue create --title "Bug: Login fails" --body "Steps to reproduce..."
gh issue create --title "Feature request" --label "enhancement" --assignee @me
gh issue create --title "Task" --project "Sprint Board"
gh issue create --body-file issue-body.md --title "Detailed issue"
gh issue create

The interactive mode (no flags) prompts for title, body, labels, assignees, projects, and milestones.

Edit

gh issue edit 123 --title "Updated title"
gh issue edit 123 --body "Updated description"
gh issue edit 123 --add-assignee @me
gh issue edit 123 --remove-assignee user1
gh issue edit 123 --add-label "bug,priority:high"
gh issue edit 123 --remove-label "wontfix"
gh issue edit 123 --add-project "Sprint Board"
gh issue edit 123 --milestone "v2.0"

Close and Reopen

gh issue close 123
gh issue close 123 --reason "not planned"
gh issue close 123 --reason completed --comment "Fixed in PR #456"
gh issue reopen 123

Close reasons: completed, not planned.

Comment

gh issue comment 123 --body "Working on this"
gh issue comment 123 --body-file comment.md
gh issue comment 123 --web

Pin and Unpin

gh issue pin 123
gh issue unpin 123

Transfer

Move an issue to another repository:

gh issue transfer 123 owner/other-repo

Lock and Unlock

gh issue lock 123 --reason "resolved"
gh issue unlock 123

Lock reasons: off-topic, too heated, resolved, spam.

Develop (Create Branch from Issue)

Create a development branch linked to an issue:

gh issue develop 123
gh issue develop 123 --base main
gh issue develop 123 --name "fix/login-bug"
gh issue develop 123 --checkout

Delete

gh issue delete 123 --yes

Status

View issues relevant to you across repositories:

gh issue status

Labels

gh label list
gh label create "priority:high" --color FF0000 --description "High priority"
gh label create "area:auth" --color 0075ca
gh label edit "bug" --color 00FF00 --description "Something is broken"
gh label delete "wontfix" --yes
gh label clone --from owner/source-repo

Projects & API

Projects (v2)

GitHub Projects v2 replaces classic project boards. All gh project commands require --owner to specify the user or organization.

List and View

gh project list --owner @me
gh project list --owner my-org
gh project list --owner @me --json number,title,url
gh project view 1 --owner @me
gh project view 1 --owner @me --web
gh project view 1 --owner @me --json title,items

Create and Edit

gh project create --owner @me --title "Sprint Board"
gh project edit 1 --owner @me --title "Updated Board"
gh project edit 1 --owner @me --description "Q1 sprint tracking"
gh project close 1 --owner @me
gh project delete 1 --owner @me
gh project copy 1 --source-owner source-org --target-owner @me --title "Copy of Board"

Items

Add issues and PRs to a project:

gh project item-add 1 --owner @me --url https://github.com/owner/repo/issues/123
gh project item-create 1 --owner @me --title "Draft item"
gh project item-list 1 --owner @me
gh project item-list 1 --owner @me --json id,title,status
gh project item-archive 1 --owner @me --id ITEM_ID
gh project item-delete 1 --owner @me --id ITEM_ID

Edit Item Fields

gh project item-edit --project-id PROJECT_ID --id ITEM_ID --field-id FIELD_ID --text "value"
gh project item-edit --project-id PROJECT_ID --id ITEM_ID --field-id FIELD_ID --single-select-option-id OPTION_ID
gh project item-edit --project-id PROJECT_ID --id ITEM_ID --field-id FIELD_ID --date "2025-01-15"
gh project item-edit --project-id PROJECT_ID --id ITEM_ID --field-id FIELD_ID --number 5
gh project item-edit --project-id PROJECT_ID --id ITEM_ID --field-id FIELD_ID --clear

Fields

gh project field-list 1 --owner @me
gh project field-create 1 --owner @me --name "Priority" --data-type SINGLE_SELECT --single-select-options "Low,Medium,High"
gh project field-create 1 --owner @me --name "Due Date" --data-type DATE
gh project field-create 1 --owner @me --name "Story Points" --data-type NUMBER
gh project field-delete 1 --owner @me --id FIELD_ID

Field data types: TEXT, SINGLE_SELECT, DATE, NUMBER.

Link and Unlink

Link a project to a repository:

gh project link 1 --owner @me --repo owner/repo
gh project unlink 1 --owner @me --repo owner/repo

Templates

gh project mark-template 1 --owner @me

REST API

gh api repos/owner/repo
gh api repos/owner/repo/issues
gh api repos/owner/repo/issues -f title="New issue" -f body="Description"
gh api repos/owner/repo/pulls/45/comments
gh api repos/owner/repo --jq '.stargazers_count'
gh api repos/owner/repo/issues --paginate
gh api repos/owner/repo -X PATCH -f description="Updated"
gh api repos/owner/repo/actions/caches --paginate --jq '.actions_caches[].key'

Key flags:

• -X, --method -- HTTP method (GET, POST, PATCH, DELETE)
• -f, --field -- add a string field
• -F, --raw-field -- add a raw field (for numbers, booleans, null)
• --paginate -- fetch all pages of results
• --jq -- filter response with jq
• -t, --template -- format output with Go template
• --hostname -- target a GitHub Enterprise host
• -H, --header -- add custom HTTP headers
• --input -- read body from file

GraphQL API

gh api graphql -f query='{ viewer { login } }'

gh api graphql -f query='
  query($owner: String!, $repo: String!) {
    repository(owner: $owner, name: $repo) {
      issues(first: 10, states: OPEN) {
        nodes { number title }
      }
    }
  }
' -f owner="owner" -f repo="repo"

gh api graphql --paginate -f query='
  query($endCursor: String) {
    viewer {
      repositories(first: 100, after: $endCursor) {
        nodes { nameWithOwner }
        pageInfo { hasNextPage endCursor }
      }
    }
  }
'

Rulesets

View and check repository rulesets:

gh ruleset list
gh ruleset list --org my-org
gh ruleset view 1
gh ruleset check --branch main

Codespaces

gh codespace list
gh codespace create --repo owner/repo
gh codespace create --repo owner/repo --machine largePremiumLinux
gh codespace ssh -c CODESPACE_NAME
gh codespace code -c CODESPACE_NAME
gh codespace stop -c CODESPACE_NAME
gh codespace delete -c CODESPACE_NAME
gh codespace ports -c CODESPACE_NAME
gh codespace logs -c CODESPACE_NAME

Status

View notifications, assigned issues, and review requests:

gh status
gh status --org my-org

Organization

gh org list

Pull Requests

List and Status

gh pr list
gh pr list --state merged --limit 20
gh pr list --label "needs-review" --assignee @me
gh pr list --base main --head feature/auth
gh pr list --draft
gh pr list --search "fix in:title"
gh pr list --json number,title,headRefName,mergeable
gh pr status

View

gh pr view 45
gh pr view 45 --web
gh pr view 45 --json title,body,reviews,statusCheckRollup
gh pr diff 45
gh pr checks 45
gh pr checks 45 --json name,state,conclusion

Create

gh pr create --title "Add feature" --body "Description"
gh pr create --fill
gh pr create --fill-first
gh pr create --fill-verbose
gh pr create --draft
gh pr create --base main --head feature/auth
gh pr create --reviewer user1,user2 --assignee @me
gh pr create --label "enhancement" --milestone "v2.0"
gh pr create --project "Sprint Board"
gh pr create --body-file pr-body.md
gh pr create --template pull_request_template.md
gh pr create --web
gh pr create --dry-run

Key flags:

• --fill -- auto-populate title and body from commits
• --fill-first -- use first commit for title, rest for body
• --fill-verbose -- include full commit messages in body
• --draft -- create as draft PR
• --dry-run -- preview without creating
• --no-maintainer-edit -- prevent maintainer edits on fork PRs

Checkout

gh pr checkout 45
gh pr checkout 45 --force
gh pr checkout 45 --detach

Edit

gh pr edit 45 --title "Updated title"
gh pr edit 45 --body "Updated description"
gh pr edit 45 --add-reviewer user1
gh pr edit 45 --remove-reviewer user2
gh pr edit 45 --add-label "ready" --remove-label "wip"
gh pr edit 45 --add-assignee @me
gh pr edit 45 --base develop
gh pr edit 45 --add-project "Sprint Board"

Review

gh pr review 45 --approve
gh pr review 45 --approve --body "LGTM"
gh pr review 45 --request-changes --body "Please fix X"
gh pr review 45 --comment --body "Consider using Y instead"

Merge

gh pr merge 45 --squash
gh pr merge 45 --merge
gh pr merge 45 --rebase
gh pr merge --squash --delete-branch
gh pr merge --squash --subject "feat: add auth (#45)"
gh pr merge --squash --body "Detailed merge description"

Auto-Merge

Enable auto-merge to merge automatically when all checks pass:

gh pr merge --auto --squash
gh pr merge --auto --squash --delete-branch
gh pr merge 45 --auto --rebase
gh pr merge --disable-auto

Auto-merge requires branch protection rules with required status checks enabled on the repository.

Mark Ready for Review

gh pr ready 45

Update Branch

Bring the PR branch up to date with the base branch:

gh pr update-branch 45
gh pr update-branch 45 --rebase

Close and Reopen

gh pr close 45
gh pr close 45 --delete-branch
gh pr reopen 45

Lock and Unlock

gh pr lock 45 --reason "resolved"
gh pr unlock 45

Revert

Create a revert PR for a merged pull request:

gh pr revert 45
gh pr revert 45 --body "Reverting due to regression"

Comment

gh pr comment 45 --body "Updated the implementation"
gh pr comment 45 --body-file review-notes.md

Quick PR Workflow

git checkout -b feature/my-feature
git add -A && git commit -m "feat: add feature"
git push -u origin feature/my-feature
gh pr create --fill

Review and Merge Workflow

gh pr checkout 45
gh pr diff
gh pr review --approve
gh pr merge --squash --delete-branch

Releases & Search

Releases

Create

gh release create v1.0.0
gh release create v1.0.0 --title "Version 1.0" --notes "Release notes"
gh release create v1.0.0 --generate-notes
gh release create v1.0.0 --generate-notes --notes-start-tag v0.9.0
gh release create v1.0.0 --draft
gh release create v1.0.0 --prerelease
gh release create v1.0.0 --target release-branch
gh release create v1.0.0 ./dist/app.zip ./dist/app.tar.gz
gh release create v1.0.0 --notes-file release-notes.md

List and View

gh release list
gh release list --limit 10
gh release list --json tagName,publishedAt,isPrerelease
gh release view v1.0.0
gh release view v1.0.0 --web
gh release view v1.0.0 --json assets

Edit

gh release edit v1.0.0 --title "Updated Title"
gh release edit v1.0.0 --notes "Updated notes"
gh release edit v1.0.0 --draft=false
gh release edit v1.0.0 --prerelease=false
gh release edit v1.0.0 --latest

Upload and Download Assets

gh release upload v1.0.0 ./dist/app.zip
gh release upload v1.0.0 ./dist/app.zip --clobber
gh release download v1.0.0
gh release download v1.0.0 --pattern "*.tar.gz"
gh release download v1.0.0 --dir ./downloads
gh release delete-asset v1.0.0 app.zip

Delete

gh release delete v1.0.0 --yes
gh release delete v1.0.0 --cleanup-tag --yes

Verify Release Artifacts

gh release verify v1.0.0
gh release verify-asset v1.0.0 app.zip

Attestation

Verify supply chain attestations for artifacts:

gh attestation verify artifact.tar.gz --owner owner
gh attestation verify artifact.tar.gz --repo owner/repo
gh attestation download artifact.tar.gz --owner owner
gh attestation trusted-root

Search

Search Repositories

gh search repos "react hooks" --limit 10
gh search repos "react hooks" --language typescript
gh search repos "cli tool" --stars ">100"
gh search repos "api" --owner my-org
gh search repos "react" --json fullName,description,stargazersCount

Search Issues and PRs

gh search issues "bug authentication" --repo owner/repo
gh search issues "memory leak" --state open --label bug
gh search issues "feature request" --assignee @me
gh search prs "fix memory leak" --state open
gh search prs "refactor" --repo owner/repo --merged

Search Code

gh search code "function handleAuth" --repo owner/repo
gh search code "TODO" --owner my-org --language typescript
gh search code "import express" --filename "server.ts"

Search Commits

gh search commits "fix auth" --repo owner/repo
gh search commits "bump version" --author user1

Gists

gh gist create file.txt --public
gh gist create file.txt --desc "Description"
gh gist create file1.txt file2.txt
echo "Hello" | gh gist create --filename hello.txt
gh gist list
gh gist list --public --limit 20
gh gist view GIST_ID
gh gist view GIST_ID --raw
gh gist edit GIST_ID
gh gist clone GIST_ID
gh gist rename GIST_ID old-name.txt new-name.txt
gh gist delete GIST_ID --yes

SSH Keys

gh ssh-key list
gh ssh-key add ~/.ssh/id_ed25519.pub --title "My laptop"
gh ssh-key add ~/.ssh/id_ed25519.pub --type signing
gh ssh-key delete KEY_ID --yes

GPG Keys

gh gpg-key list
gh gpg-key add key.gpg
gh gpg-key delete KEY_ID --yes

Repos & Auth

Authentication

gh auth login
gh auth login --with-token < token.txt
gh auth status
gh auth status --json
gh auth token
gh auth refresh -s read:org,admin:public_key
gh auth switch
gh auth logout
gh auth setup-git

Key flags for gh auth login:

• --hostname -- authenticate with a specific GitHub host (GitHub Enterprise)
• --web -- open a browser for authentication
• --with-token -- read token from stdin
• --scopes -- request additional OAuth scopes

Check current authentication and scopes:

gh auth status

Repositories

Clone and Fork

gh repo clone owner/repo
gh repo clone owner/repo -- --depth 1
gh repo fork owner/repo --clone
gh repo fork owner/repo --clone --remote

Create

gh repo create my-repo --public
gh repo create my-repo --private --clone
gh repo create my-repo --public --source=. --push
gh repo create org/my-repo --internal --template owner/template-repo

View and List

gh repo view
gh repo view owner/repo --web
gh repo view --json name,description,url
gh repo list owner --limit 50
gh repo list owner --json name,isPrivate --jq '.[].name'

Edit and Manage

gh repo edit --description "New description"
gh repo edit --default-branch main
gh repo edit --enable-issues --enable-wiki=false
gh repo archive owner/repo
gh repo unarchive owner/repo
gh repo rename new-name
gh repo delete owner/repo --yes

Sync

Sync a fork with its upstream:

gh repo sync owner/my-fork
gh repo sync --source owner/upstream
gh repo set-default owner/repo

Deploy Keys

gh repo deploy-key list
gh repo deploy-key add key.pub --title "CI server"
gh repo deploy-key delete 12345

Autolinks

gh repo autolink list
gh repo autolink create "TICKET-" "https://jira.example.com/browse/TICKET-<num>"
gh repo autolink view 1
gh repo autolink delete 1

Gitignore and License Templates

gh repo gitignore list
gh repo gitignore view Node
gh repo license list
gh repo license view mit

Configuration

gh config list
gh config set editor vim
gh config set browser "open"
gh config set git_protocol ssh
gh config get editor
gh config clear-cache

Browse

Open the current repository in the browser:

gh browse
gh browse --settings
gh browse --projects
gh browse src/main.ts
gh browse src/main.ts:42

Extensions

gh extension list
gh extension install owner/gh-extension-name
gh extension search query
gh extension browse
gh extension upgrade --all
gh extension remove extension-name
gh extension create my-extension

Aliases

gh alias set pv 'pr view'
gh alias set bugs 'issue list --label bug'
gh alias list
gh alias delete pv
gh alias import aliases.yml

JSON Output and Scripting

Most gh commands support structured output for scripting:

gh pr list --json number,title,author --jq '.[] | "\(.number): \(.title)"'
gh issue list --json number,title,labels --jq '.[] | select(.labels | length > 0)'
gh repo list --json name,isPrivate -t '{{range .}}{{.name}}{{"\n"}}{{end}}'

Key flags:

• --json fields -- output JSON with specified fields
• --jq expression -- filter JSON with jq syntax
• -t, --template -- format JSON with Go templates