--- name: gh-helper description: | Complete GitHub operations via gh CLI - repos, issues, PRs, code search, releases, file management When user mentions GitHub, repositories, issues, PRs, gh command, code search, commits, file contents --- # GitHub CLI Helper Agent ## Overview Complete GitHub operations via `gh` CLI and GitHub API. This skill replaces GitHub MCP server functionality, providing CLI/API equivalents for all operations. ## Monorepo workflow guard In `shepherdjerred/monorepo`, `monorepo-delivery` is authoritative for every feature branch and PR. Use `toolkit gh` here for inspection, review comments, and other explicitly requested GitHub operations; it supplies this repository as the default and otherwise preserves native CLI behavior. Do not create branches, create feature PRs, or merge them with the generic `gh` examples below. Load `monorepo-delivery` before any branch or feature-PR mutation. This monorepo uses Woodpecker CI, not GitHub Actions. Use `toolkit ci wait` for merge readiness, `toolkit ci explain` for blockers, and `toolkit woodpecker` for native CI operations. The generic Actions examples later in this skill apply only to repositories that actually use GitHub Actions. ## MCP Tool Equivalents Reference | MCP Tool | CLI/API Equivalent | | ---------------------------- | ------------------------------------------------------------------ | | `create_or_update_file` | `gh api -X PUT /repos/{owner}/{repo}/contents/{path}` | | `search_repositories` | `gh search repos ` | | `create_repository` | `gh repo create ` | | `get_file_contents` | `gh api /repos/{owner}/{repo}/contents/{path}` | | `push_files` | `git add && git commit && git push` | | `create_issue` | `gh issue create` | | `create_pull_request` | `gh pr create` | | `fork_repository` | `gh repo fork` | | `create_branch` | `gh api -X POST /repos/{owner}/{repo}/git/refs` | | `list_commits` | `gh api /repos/{owner}/{repo}/commits` | | `list_issues` | `gh issue list` | | `update_issue` | `gh issue edit` | | `add_issue_comment` | `gh issue comment` | | `search_code` | `gh search code ` | | `search_issues` | `gh search issues ` | | `search_users` | `gh api /search/users?q=` | | `get_issue` | `gh issue view ` | | `get_pull_request` | `gh pr view ` | | `list_pull_requests` | `gh pr list` | | `create_pull_request_review` | `gh pr review` | | `merge_pull_request` | `gh pr merge` | | `get_pull_request_files` | `gh api /repos/{owner}/{repo}/pulls/{number}/files` | | `get_pull_request_status` | `gh pr checks` | | `update_pull_request_branch` | `gh api -X PUT /repos/{owner}/{repo}/pulls/{number}/update-branch` | | `get_pull_request_comments` | `gh api /repos/{owner}/{repo}/pulls/{number}/comments` | | `get_pull_request_reviews` | `gh api /repos/{owner}/{repo}/pulls/{number}/reviews` | ## Auto-Approved Commands Safe read-only commands: - `gh repo view`, `gh repo list` - `gh issue list`, `gh issue view` - `gh pr list`, `gh pr view`, `gh pr diff`, `gh pr checks` - `gh release list`, `gh release view` - `gh search repos`, `gh search code`, `gh search issues` - `gh status` --- ## Repository Operations ### Search Repositories ```bash # Basic search gh search repos "kubernetes operator" # With filters gh search repos "react" --language typescript --stars ">1000" gh search repos "cli tool" --owner hashicorp gh search repos "mcp server" --topic model-context-protocol # JSON output for parsing gh search repos "query" --json fullName,description,stargazersCount ``` ### Create Repository ```bash # Interactive creation gh repo create # Create with options gh repo create my-repo --public --description "My project" gh repo create my-repo --private --clone # Create from template gh repo create my-repo --template owner/template-repo # Create org repo gh repo create my-org/my-repo --public ``` ### Fork Repository ```bash # Fork to your account gh repo fork owner/repo # Fork and clone gh repo fork owner/repo --clone # Fork to organization gh repo fork owner/repo --org my-org # Fork with custom name gh repo fork owner/repo --fork-name my-fork ``` ### Get File Contents ```bash # Get file content via API (returns base64) gh api /repos/{owner}/{repo}/contents/{path} | jq -r '.content' | base64 -d # Get file from specific branch gh api /repos/{owner}/{repo}/contents/{path}?ref=branch-name # Get directory listing gh api /repos/{owner}/{repo}/contents/{path} # Get raw file content gh api /repos/{owner}/{repo}/contents/{path} -H "Accept: application/vnd.github.raw" ``` ### Create or Update File ```bash # Create new file gh api -X PUT /repos/{owner}/{repo}/contents/{path} \ -f message="Add new file" \ -f content="$(echo 'file content' | base64)" \ -f branch="main" # Update existing file (requires SHA) SHA=$(gh api /repos/{owner}/{repo}/contents/{path} | jq -r '.sha') gh api -X PUT /repos/{owner}/{repo}/contents/{path} \ -f message="Update file" \ -f content="$(echo 'new content' | base64)" \ -f sha="$SHA" \ -f branch="main" ``` ### Push Multiple Files Use git commands for pushing multiple files: ```bash # Stage and commit multiple files git add file1.txt file2.txt git commit -m "Add multiple files" git push origin branch-name # Or use a single commit for all changes git add . git commit -m "Update files" git push ``` ### Create Branch ```bash # Via git (local) git checkout -b new-branch git push -u origin new-branch # Via API (remote, from default branch) SHA=$(gh api /repos/{owner}/{repo}/git/refs/heads/main | jq -r '.object.sha') gh api -X POST /repos/{owner}/{repo}/git/refs \ -f ref="refs/heads/new-branch" \ -f sha="$SHA" # From specific branch SHA=$(gh api /repos/{owner}/{repo}/git/refs/heads/source-branch | jq -r '.object.sha') gh api -X POST /repos/{owner}/{repo}/git/refs \ -f ref="refs/heads/new-branch" \ -f sha="$SHA" ``` ### List Commits ```bash # List commits via CLI git log --oneline -20 # List commits via API gh api /repos/{owner}/{repo}/commits # With filters gh api "/repos/{owner}/{repo}/commits?sha=branch&per_page=10" gh api "/repos/{owner}/{repo}/commits?author=username" gh api "/repos/{owner}/{repo}/commits?since=2024-01-01T00:00:00Z" # JSON output gh api /repos/{owner}/{repo}/commits --jq '.[].commit.message' ``` --- ## Issue Operations ### List Issues ```bash # List open issues gh issue list # With filters gh issue list --state open gh issue list --state closed gh issue list --state all gh issue list --assignee @me gh issue list --assignee username gh issue list --author @me gh issue list --label bug gh issue list --label "bug,priority:high" gh issue list --milestone "v1.0" # Search with query gh issue list --search "is:open label:bug" # JSON output gh issue list --json number,title,state,labels ``` ### Get Issue Details ```bash # View issue gh issue view 123 # View in web browser gh issue view 123 --web # JSON output gh issue view 123 --json number,title,body,state,labels,assignees,comments # Get comments gh issue view 123 --comments ``` ### Create Issue ```bash # Interactive gh issue create # With options gh issue create --title "Bug report" --body "Description" gh issue create --title "Feature" --label enhancement --assignee @me gh issue create --title "Bug" --milestone "v1.0" --project "Board" # From file gh issue create --title "Issue" --body-file issue-body.md # Open in editor gh issue create --title "Issue" --editor ``` ### Update Issue ```bash # Edit title gh issue edit 123 --title "New title" # Edit body gh issue edit 123 --body "New description" gh issue edit 123 --body-file updated.md # Modify labels gh issue edit 123 --add-label "priority:high" gh issue edit 123 --remove-label "needs-triage" # Modify assignees gh issue edit 123 --add-assignee username gh issue edit 123 --remove-assignee username # Change milestone gh issue edit 123 --milestone "v2.0" # Close/reopen gh issue close 123 gh issue reopen 123 ``` ### Add Issue Comment ```bash # Add comment gh issue comment 123 --body "This is a comment" # From file gh issue comment 123 --body-file comment.md # Open in editor gh issue comment 123 --editor # Edit last comment gh issue comment 123 --edit-last --body "Updated comment" ``` ### Search Issues ```bash # Basic search gh search issues "memory leak" # With filters gh search issues "bug" --repo owner/repo gh search issues "type:bug" --state open gh search issues "label:critical" --assignee username gh search issues "is:pr is:merged" --author username # JSON output gh search issues "query" --json number,title,repository,state ``` --- ## Pull Request Operations ### List Pull Requests ```bash # List open PRs gh pr list # With filters gh pr list --state open gh pr list --state closed gh pr list --state merged gh pr list --state all gh pr list --author @me gh pr list --assignee username gh pr list --label "needs-review" gh pr list --base main gh pr list --head feature-branch # Search with query gh pr list --search "is:open review:required" # JSON output gh pr list --json number,title,state,author,labels ``` ### Get Pull Request Details ```bash # View PR gh pr view 123 # View in web gh pr view 123 --web # JSON output gh pr view 123 --json number,title,body,state,author,labels,reviews,commits,files # View comments gh pr view 123 --comments ``` ### Create Pull Request For `shepherdjerred/monorepo`, use `git-spice branch submit` or `git-spice stack submit` instead. The commands below are for repositories that do not use git-spice. ```bash # Interactive gh pr create # With options gh pr create --title "Fix bug" --body "Description" gh pr create --title "Feature" --base main --head feature-branch gh pr create --fill # Use commit info gh pr create --draft # Create as draft # With reviewers gh pr create --title "PR" --reviewer user1,user2 gh pr create --title "PR" --reviewer team:my-team # With labels and assignees gh pr create --title "PR" --label bug --assignee @me # Open in web to finish gh pr create --web ``` ### Get Pull Request Files ```bash # View diff gh pr diff 123 # Via API (detailed file info) gh api /repos/{owner}/{repo}/pulls/123/files # JSON with additions/deletions gh api /repos/{owner}/{repo}/pulls/123/files --jq '.[] | {filename, status, additions, deletions}' ``` ### Get Pull Request Status/Checks ```bash # View checks gh pr checks 123 # Watch checks in real-time gh pr checks 123 --watch # Wait for checks to complete gh pr checks 123 --watch --fail-level all # JSON output gh pr checks 123 --json name,state,conclusion ``` ### Create Pull Request Review ```bash # Approve gh pr review 123 --approve # Request changes gh pr review 123 --request-changes --body "Please fix the tests" # Comment only gh pr review 123 --comment --body "Looks good so far" # Add inline comments via API gh api -X POST /repos/{owner}/{repo}/pulls/123/reviews \ -f body="Review comment" \ -f event="COMMENT" \ -f comments='[{"path":"file.js","position":10,"body":"Consider refactoring"}]' ``` ### Get Pull Request Reviews ```bash # Via API gh api /repos/{owner}/{repo}/pulls/123/reviews # Get review details gh api /repos/{owner}/{repo}/pulls/123/reviews --jq '.[] | {user: .user.login, state: .state, body: .body}' ``` ### Get Pull Request Comments ```bash # Review comments (inline) gh api /repos/{owner}/{repo}/pulls/123/comments # Issue comments (general) gh api /repos/{owner}/{repo}/issues/123/comments # All comments with details gh api /repos/{owner}/{repo}/pulls/123/comments --jq '.[] | {user: .user.login, body: .body, path: .path}' ``` ### Merge Pull Request For `shepherdjerred/monorepo`, merging is handled through the repository's approved git-spice workflow and explicit human/operator action. Do not use these generic commands for feature work in this repository. ```bash # Merge (default method) gh pr merge 123 # Squash merge gh pr merge 123 --squash # Rebase merge gh pr merge 123 --rebase # Delete branch after merge gh pr merge 123 --delete-branch # Auto-merge when checks pass gh pr merge 123 --auto --squash # With custom commit message gh pr merge 123 --squash --subject "feat: Add feature" --body "Detailed description" ``` ### Update Pull Request Branch ```bash # Via API gh api -X PUT /repos/{owner}/{repo}/pulls/123/update-branch \ -f expected_head_sha="current-head-sha" # Or use git locally gh pr checkout 123 git merge main git push ``` --- ## Code Search ### Search Code ```bash # Basic search gh search code "function authenticate" # In specific repo gh search code "TODO" --repo owner/repo # With language filter gh search code "interface User" --language typescript # With path filter gh search code "config" --filename "*.yaml" # JSON output gh search code "query" --json path,repository,textMatches ``` ### Search Users ```bash # Via API gh api "/search/users?q=fullname:John+type:user" # With filters gh api "/search/users?q=location:Seattle+followers:>100" # Search by email domain gh api "/search/users?q=email:@company.com" ``` --- ## Releases ### List Releases ```bash gh release list gh release list --limit 10 ``` ### View Release ```bash gh release view v1.0.0 gh release view latest ``` ### Create Release ```bash # Create release gh release create v1.0.0 # With options gh release create v1.0.0 --title "Version 1.0.0" --notes "Release notes" gh release create v1.0.0 --generate-notes gh release create v1.0.0 --draft gh release create v1.0.0 --prerelease # Upload assets gh release create v1.0.0 ./dist/*.tar.gz ``` --- ## Authentication & Configuration ### Authentication ```bash # Login (interactive) gh auth login # With clipboard (OAuth code auto-copied) gh auth login --clipboard # Check status gh auth status # Switch accounts gh auth switch # Logout gh auth logout ``` ### Configuration ```bash # Set editor gh config set editor "code --wait" gh config set editor vim # Create aliases gh alias set prs 'pr list --author @me' gh alias set co 'pr checkout' gh alias set issues 'issue list --assignee @me' # List aliases gh alias list ``` ### Browse (Terminal to Web) ```bash # Open repo in browser gh browse # Open specific PR gh browse 123 # Open issues page gh browse -- issues # Open settings gh browse -- settings # Open file gh browse -- src/main.ts ``` --- ## Advanced API Usage For any operation not covered by `gh` commands: ```bash # GET request gh api /repos/{owner}/{repo}/issues # POST request gh api -X POST /repos/{owner}/{repo}/issues \ -f title="New issue" \ -f body="Description" # PUT request gh api -X PUT /repos/{owner}/{repo}/issues/123 \ -f state="closed" # DELETE request gh api -X DELETE /repos/{owner}/{repo}/issues/comments/456 # With pagination gh api /repos/{owner}/{repo}/issues --paginate # JSON parsing with jq gh api /repos/{owner}/{repo}/issues --jq '.[].title' # GraphQL queries gh api graphql -f query=' query { repository(owner: "owner", name: "repo") { issues(first: 10) { nodes { title number } } } } ' ``` --- ## Common Workflows ### Complete PR Workflow (repositories without git-spice) ```bash # Create branch and make changes git checkout -b feature/new-thing # ... make changes ... git add path/to/changed-file && git commit -m "Add new feature" git push -u origin feature/new-thing # Create PR gh pr create --fill # Check status and merge gh pr checks --watch gh pr merge --squash --delete-branch ``` ### Daily PR Review Routine ```bash # PRs waiting for your review gh pr list --search "review-requested:@me" # Your open PRs gh pr list --author @me # Check PR status gh pr checks --watch ``` ### Release Workflow ```bash # Create and push tag git tag v1.0.0 git push origin v1.0.0 # Create release with auto-generated notes gh release create v1.0.0 --generate-notes # Upload release assets gh release upload v1.0.0 ./dist/*.tar.gz ``` --- ## When to Ask for Help Ask the user for clarification when: - Repository owner/name is ambiguous - Multiple PRs or issues match criteria - Authentication or permissions issues arise - Workflow involves destructive operations (force push, delete) - Need to determine correct branch or ref