GitHub CLI Workflows

Prerequisites

Ensure gh is authenticated:

gh auth status

Issues

Create Issue

gh issue create --title "Brief descriptive title" --body "$(cat <<'EOF'
## Summary
One-paragraph description of what needs to be done and why.

## Requirements
- [ ] Requirement 1
- [ ] Requirement 2
- [ ] Requirement 3

## Acceptance Criteria
- [ ] Criterion 1
- [ ] Criterion 2

## Notes
Additional context, links, or considerations.
EOF
)" --label "label1,label2"

Issue Title Conventions:

• Start with action verb: Add, Fix, Update, Remove, Refactor, Implement
• Be specific: “Add user authentication” not “Auth stuff”
• Keep under 72 characters

Read Issues

# List open issues
gh issue list

# List with filters
gh issue list --label "bug" --assignee "@me"

# View specific issue
gh issue view 123

# View with comments
gh issue view 123 --comments

Update Issue

# Add labels
gh issue edit 123 --add-label "priority:high,scope:mls"

# Remove labels
gh issue edit 123 --remove-label "needs-triage"

# Change title
gh issue edit 123 --title "New title"

# Add to milestone
gh issue edit 123 --milestone "v1.0"

# Assign
gh issue edit 123 --add-assignee "@me"

Close Issue

# Close with reason
gh issue close 123 --reason completed

# Close as not planned
gh issue close 123 --reason "not planned"

Labels

Create Label

gh label create "scope:feature-name" --description "Features for X" --color "0052CC"

Label Naming Conventions:

• Use prefixes with colon: scope:, priority:, type:, status:
• Lowercase with hyphens: scope:user-auth
• Common prefixes:
  • type:bug, type:feature, type:refactor, type:docs
  • priority:high, priority:medium, priority:low
  • scope:mls, scope:post-mls
  • status:blocked, status:in-review

List Labels

gh label list

Update Label

gh label edit "old-name" --name "new-name" --description "Updated description" --color "FF0000"

Delete Label

gh label delete "label-name" --yes

Pull Requests

Determine Base Branch

CRITICAL: Always verify the correct base branch before creating a PR.

# Check current branch
git branch --show-current

# See what branch you branched from
git log --oneline --graph -10

# List remote branches
git branch -r

# Common base branches: main, master, develop, release/*

Create PR (Closing Issues)

PRs MUST reference issues they implement using closing keywords.

gh pr create \
  --base develop \
  --title "Add user authentication" \
  --body "$(cat <<'EOF'
## Summary
Brief description of what this PR does.

## Changes
- Change 1
- Change 2
- Change 3

## Closes
Closes #123
Closes #124

## Testing
- [ ] Unit tests added/updated
- [ ] Manual testing completed
- [ ] No regressions

## Screenshots
(if applicable)
EOF
)"

Closing Keywords (any of these work):

• Closes #123
• Fixes #123
• Resolves #123

PR Title Conventions:

• Match the issue title or summarize the change
• Use imperative mood: “Add feature” not “Added feature”
• Keep under 72 characters

Create PR from Issue

When implementing an issue, reference it properly:

# Get issue details first
gh issue view 123

# Create branch named after issue
git checkout -b 123-add-user-auth

# After commits, create PR
gh pr create \
  --base main \
  --title "Add user authentication" \
  --body "$(cat <<'EOF'
## Summary
Implements user authentication with JWT tokens.

## Closes
Closes #123

## Changes
- Added auth middleware
- Added login/logout endpoints
- Added JWT token generation

## Testing
- [ ] Unit tests pass
- [ ] Integration tests pass
EOF
)"

Read PRs

# List open PRs
gh pr list

# View specific PR
gh pr view 456

# View PR diff
gh pr diff 456

# View PR checks
gh pr checks 456

# View PR comments
gh api repos/{owner}/{repo}/pulls/456/comments

Update PR

# Change title
gh pr edit 456 --title "New title"

# Add reviewers
gh pr edit 456 --add-reviewer "username1,username2"

# Add labels
gh pr edit 456 --add-label "ready-for-review"

# Change base branch
gh pr edit 456 --base develop

Merge PR

# Merge (creates merge commit)
gh pr merge 456 --merge

# Squash merge (single commit)
gh pr merge 456 --squash

# Rebase merge
gh pr merge 456 --rebase

# Delete branch after merge
gh pr merge 456 --squash --delete-branch

Close PR Without Merging

gh pr close 456

Complete Workflow Example

Feature Development Flow

# 1. Create issue
gh issue create \
  --title "Add dark mode toggle" \
  --label "type:feature,scope:mls" \
  --body "$(cat <<'EOF'
## Summary
Add a dark mode toggle to user settings.

## Requirements
- [ ] Toggle switch in settings
- [ ] Persist preference
- [ ] Apply theme immediately

## Acceptance Criteria
- [ ] User can toggle dark mode
- [ ] Preference persists across sessions
EOF
)"
# Returns: Created issue #167

# 2. Create feature branch
git checkout -b 167-add-dark-mode

# 3. Make changes and commit
git add .
git commit -m "Add dark mode toggle component"

# 4. Push and create PR
git push -u origin 167-add-dark-mode

gh pr create \
  --base main \
  --title "Add dark mode toggle" \
  --body "$(cat <<'EOF'
## Summary
Adds dark mode toggle to user settings with persistent preferences.

## Closes
Closes #167

## Changes
- Added DarkModeToggle component
- Added theme context provider
- Added localStorage persistence

## Testing
- [x] Unit tests added
- [x] Manual testing completed
EOF
)"

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

Tips

Batch Operations

# Close multiple issues
for i in 101 102 103; do gh issue close $i; done

# Add label to multiple issues
for i in 101 102 103; do gh issue edit $i --add-label "wontfix"; done

JSON Output for Scripting

# Get issue data as JSON
gh issue view 123 --json number,title,labels,state

# List PRs as JSON
gh pr list --json number,title,headRefName,baseRefName

Check Repo Context

# Verify which repo you're working with
gh repo view --json nameWithOwner