--- name: github-cli description: GitHub CLI workflows for issues, labels, and PRs with proper linking, base branch handling, and structured descriptions license: MIT compatibility: opencode metadata: scope: global tools: gh --- # GitHub CLI Workflows ## Prerequisites Ensure `gh` is authenticated: ```bash gh auth status ``` ## Issues ### Create Issue ```bash 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 ```bash # 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 ```bash # 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 ```bash # Close with reason gh issue close 123 --reason completed # Close as not planned gh issue close 123 --reason "not planned" ``` ## Labels ### Create Label ```bash 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 ```bash gh label list ``` ### Update Label ```bash gh label edit "old-name" --name "new-name" --description "Updated description" --color "FF0000" ``` ### Delete Label ```bash gh label delete "label-name" --yes ``` ## Pull Requests ### Determine Base Branch **CRITICAL: Always verify the correct base branch before creating a PR.** ```bash # 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.** ```bash 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: ```bash # 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 ```bash # 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 ```bash # 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 ```bash # 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 ```bash gh pr close 456 ``` ## Complete Workflow Example ### Feature Development Flow ```bash # 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 ```bash # 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 ```bash # 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 ```bash # Verify which repo you're working with gh repo view --json nameWithOwner ```