| applyTo | **/* |
|---|---|
| description | GitHub CLI usage guidelines and best practices (operational instructions for running gh commands, not file-specific) |
Instructions for using GitHub CLI (gh) for repository operations.
Verify authentication before performing operations:
# Check current authentication status
gh auth status
# If not authenticated
gh auth login# List repositories in an organization
gh repo list <org> --limit 100
# Get repository default branch (don't assume main)
gh api repos/<owner>/<repo> --jq '.default_branch'
# View repository details
gh repo view <owner>/<repo># Clone a repository
gh repo clone <owner>/<repo>
# Fork a repository
gh repo fork <owner>/<repo> --clone# Create a new issue
gh issue create --title "Issue Title" --body "Issue description"
# Create with labels and assignee
gh issue create --title "Bug: Login fails" --body "Description" --label "bug" --assignee "@me"
# Create interactively
gh issue create# List open issues
gh issue list
# View specific issue
gh issue view <number>
# Search issues
gh issue list --search "bug in:title"Common labels to use:
bug- Something isn't workingenhancement- New feature or requestdocumentation- Documentation improvementsquestion- Further information requestedgood first issue- Good for newcomers
# Create PR from current branch
gh pr create --title "PR Title" --body "Description"
# Create draft PR
gh pr create --title "WIP: Feature" --body "Work in progress" --draft
# Create PR with specific base branch
gh pr create --base develop --title "Feature" --body "Description"# List PRs awaiting review
gh pr list --search "review-requested:@me"
# View PR details
gh pr view <number>
# Checkout PR locally
gh pr checkout <number>
# Approve PR
gh pr review <number> --approve
# Request changes
gh pr review <number> --request-changes --body "Please fix..."# Merge PR
gh pr merge <number>
# Merge with squash
gh pr merge <number> --squash
# Merge with rebase
gh pr merge <number> --rebase
# Delete branch after merge
gh pr merge <number> --delete-branch# List workflow runs
gh run list
# View specific run
gh run view <run-id>
# Watch a running workflow
gh run watch <run-id>
# Re-run failed jobs
gh run rerun <run-id> --failed# View run logs
gh run view <run-id> --log
# View failed step logs
gh run view <run-id> --log-failedUse --notes-file (write notes to a temporary file first) rather than --notes to avoid
escaping issues with backticks, backslashes, and quotes. For project releases, the rules in
releases.instructions.md take precedence over these examples.
# Create release from tag (write notes to a file first to avoid escaping issues)
printf '## Highlights\n\n- Your release notes here\n' > release-notes.md
gh release create v1.0.0 --title "Version 1.0.0" --notes-file release-notes.md
rm release-notes.md
# Create release with auto-generated notes
gh release create v1.0.0 --generate-notes
# Create draft release
gh release create v1.0.0 --draft --title "Version 1.0.0"
# Upload assets
gh release create v1.0.0 ./dist/*.zip --title "Version 1.0.0"# List releases
gh release list
# View latest release
gh release view --latest# GET request
gh api repos/<owner>/<repo>
# POST request
gh api repos/<owner>/<repo>/issues --method POST -f title="Title" -f body="Body"
# Use jq for filtering
gh api repos/<owner>/<repo>/pulls --jq '.[].title'# Verify you're in a git repository
gh repo view --json nameWithOwner --jq '.nameWithOwner'
# Verify authentication
gh auth status# Create issue and capture the issue number
ISSUE_NUM=$(gh issue create --title "Feature: New functionality" --body "Description" --json number --jq '.number')
# Create feature branch using the captured issue number
git checkout -b "feature/issue-${ISSUE_NUM}-new-functionality"
# Push and create PR
git push -u origin "feature/issue-${ISSUE_NUM}-new-functionality"
gh pr create --title "Feature: New functionality" --body "Closes #${ISSUE_NUM}"--json- Output as JSON--jq- Filter JSON output--web- Open in browser--help- Show help for any command
Useful environment variables:
GH_TOKEN- Authentication tokenGH_HOST- GitHub hostname (for enterprise)GH_REPO- Default repositoryGH_EDITOR- Editor for composing text