--- name: github description: "GitHub CLI patterns for issues, projects, and PRs. Invoke when: creating issues, linking PRs to issues, updating project status, or any GitHub project operations." user-invocable: false --- # GitHub CLI Patterns Generic patterns for GitHub operations using `gh` CLI. --- ## Issues ### Creating Issues ```bash gh issue create \ --repo / \ --title "Issue title" \ --body "## Summary Description of what and why. ## Acceptance Criteria - [ ] Criterion 1 - [ ] Criterion 2" ``` With project board: ```bash gh issue create \ --repo / \ --title "Issue title" \ --body "..." \ --project "" ``` ### Issue Operations ```bash # List issues gh issue list --repo / # View issue gh issue view --repo / # Edit issue gh issue edit --repo / # Add comment gh issue comment --repo / --body "..." # Search across org gh search issues --owner "search terms" # Get issue node ID (for GraphQL) gh issue view --repo / --json id --jq '.id' ``` --- ## Project Boards (v2) ### Adding to Project ```bash gh project item-add --owner \ --url https://github.com///issues/ # List project items gh project item-list --owner ``` ### Getting Project Item ID Required for status updates: ```bash gh api graphql -f query=' query($url: URI!) { resource(url: $url) { ... on Issue { projectItems(first: 1) { nodes { id } } } } }' -f url="https://github.com///issues/" --jq '.data.resource.projectItems.nodes[0].id' ``` ### Setting Status ```bash gh api graphql -f query=' mutation { updateProjectV2ItemFieldValue(input: { projectId: "" itemId: "" fieldId: "" value: { singleSelectOptionId: "" } }) { projectV2Item { id } } }' ``` ### Setting Issue Type ```bash gh api graphql -f query=' mutation { updateIssue(input: { id: "", issueTypeId: "" }) { issue { title issueType { name } } } }' ``` --- ## Pull Requests ### Creating PRs ```bash gh pr create \ --repo / \ --title "feat: short description" \ --body "## Summary What was done. ## Changes - Change 1 - Change 2 Closes #" ``` ### PR Operations ```bash # List PRs gh pr list --repo / # View PR gh pr view --repo / # Check PR status gh pr checks --repo / ``` --- ## Linking PRs to Issues Include in PR body to auto-close: ``` Closes #123 Fixes #123 Resolves #123 ``` Cross-repo reference: ``` Closes /#123 ``` Reference without closing: ``` Related to #123 ``` --- ## Sub-Issues GitHub's native parent-child issue hierarchy for cross-repo coordination. ### Adding Sub-Issues ```bash # Get parent issue ID PARENT_ID=$(gh issue view --repo / --json id --jq '.id') # Add sub-issue by URL gh api graphql -f query=" mutation { addSubIssue(input: { issueId: \"$PARENT_ID\" subIssueUrl: \"https://github.com///issues/\" }) { issue { title } subIssue { title url } } }" ``` ### Viewing Sub-Issues ```bash gh api graphql -f query=' query($url: URI!) { resource(url: $url) { ... on Issue { title subIssues(first: 10) { nodes { title url state } } } } }' -f url="https://github.com///issues/" ``` ### Removing Sub-Issues ```bash # Get both issue IDs PARENT_ID=$(gh issue view --repo / --json id --jq '.id') SUB_ID=$(gh issue view --repo / --json id --jq '.id') # Remove sub-issue gh api graphql -f query=" mutation { removeSubIssue(input: { issueId: \"$PARENT_ID\" subIssueId: \"$SUB_ID\" }) { issue { title } subIssue { title } } }" ``` --- ## Quick Reference | Action | Command | | -------------- | --------------------------------------------- | | Create issue | `gh issue create --repo / ...` | | Add to project | `gh project item-add --owner ...` | | List issues | `gh issue list --repo /` | | View issue | `gh issue view --repo /` | | Search org | `gh search issues --owner "query"` | | Create PR | `gh pr create --repo / ...` |

github

Scan your own AI components