GitHub CLI Skill

Query GitHub for CI/CD pipeline monitoring, issue tracking, and pull request inspection using the gh CLI. This skill is READ-ONLY by default.

When This Skill MUST Be Used

ALWAYS invoke this skill when the user's request involves ANY of these:

•Checking CI/CD pipeline status or failures
•Viewing or investigating workflow runs
•Listing or viewing pull requests
•Listing or viewing issues
•Checking PR review status or merge readiness
•Debugging GitHub Actions failures
•Viewing repository information
•Any gh CLI operation

If the user asks about CI, PRs, issues, or GitHub workflows, use this skill.

Critical Safety Rules

NEVER (without explicit user approval):

•gh issue create, gh issue close, gh issue edit, gh issue comment
•gh pr create, gh pr merge, gh pr close, gh pr edit, gh pr review
•gh run rerun, gh workflow run
•gh label create, gh label delete
•Any command that creates, modifies, or deletes resources

ALWAYS allowed (read-only):

•gh run list, gh run view, gh run watch
•gh issue list, gh issue view
•gh pr list, gh pr view, gh pr diff, gh pr checks
•gh workflow list, gh workflow view
•gh repo view
•gh auth status
•Any --json query or inspection command

Approval Request Format

Before any state-changing operation, ask:

code

I need to run a state-changing GitHub command:
  Command: gh pr merge 123 --squash
  Impact: Will merge PR #123 into main branch
  Repository: owner/repo

Do you approve? (yes/no)

Quick Reference

Task	Command
Check auth	`gh auth status`
List failed runs	`gh run list --status failure`
View run logs	`gh run view <id> --log-failed`
List open PRs	`gh pr list`
View PR checks	`gh pr checks <number>`
List open issues	`gh issue list`
View repo	`gh repo view`

CI/CD Pipelines

List Workflow Runs

bash

# List recent workflow runs
gh run list

# List runs for specific workflow
gh run list --workflow build.yml

# List runs for specific branch
gh run list --branch main

# List only failed runs
gh run list --status failure

# JSON output for parsing
gh run list --json status,conclusion,name,headBranch,createdAt

View Workflow Run Details

bash

# View specific run
gh run view <run-id>

# View run with job details
gh run view <run-id> --json jobs

# View failed steps
gh run view <run-id> --json jobs --jq '.jobs[] | select(.conclusion=="failure") | {name, steps: [.steps[] | select(.conclusion=="failure")]}'

# Get run URL
gh run view <run-id> --json url -q .url

View Workflow Logs

bash

# View logs for failed jobs only
gh run view <run-id> --log-failed

# Download logs to file
gh run view <run-id> --log > run-logs.txt

# View specific job logs
gh run view <run-id> --job <job-id> --log

Watch Running Workflow

bash

# Watch run in progress (live updates)
gh run watch <run-id>

# Watch and exit with run's exit code
gh run watch <run-id> --exit-status

Rerun Workflows (REQUIRES APPROVAL)

bash

# Rerun failed jobs only - ASK APPROVAL FIRST
gh run rerun <run-id> --failed

# Rerun entire workflow - ASK APPROVAL FIRST
gh run rerun <run-id>

Issues

List Issues

bash

# List open issues
gh issue list

# List all issues (including closed)
gh issue list --state all

# List issues assigned to me
gh issue list --assignee @me

# List issues by label
gh issue list --label bug

# Search issues
gh issue list --search "memory leak"

# JSON output
gh issue list --json number,title,state,labels,assignees

View Issue

bash

# View issue details
gh issue view <issue-number>

# View in browser
gh issue view <issue-number> --web

# View with comments
gh issue view <issue-number> --comments

# JSON output
gh issue view <issue-number> --json title,body,state,labels,assignees,comments

Create/Update Issue (REQUIRES APPROVAL)

bash

# Create issue - ASK APPROVAL FIRST
gh issue create --title "Bug: Application crashes" --body "Steps to reproduce..."

# Add comment - ASK APPROVAL FIRST
gh issue comment <issue-number> --body "Working on this"

# Close issue - ASK APPROVAL FIRST
gh issue close <issue-number>

Pull Requests

List Pull Requests

bash

# List open PRs
gh pr list

# List my PRs
gh pr list --author @me

# List PRs for review
gh pr list --search "review-requested:@me"

# List PRs by label
gh pr list --label "needs-review"

# JSON output
gh pr list --json number,title,state,author,reviewDecision,mergeable

View Pull Request

bash

# View PR details
gh pr view <pr-number>

# View in browser
gh pr view <pr-number> --web

# View PR diff
gh pr diff <pr-number>

# View PR checks/CI status
gh pr checks <pr-number>

# Watch PR checks (live)
gh pr checks <pr-number> --watch

# JSON output
gh pr view <pr-number> --json title,body,state,reviews,comments,commits,files

Checkout PR Locally (Safe)

bash

# Checkout PR branch
gh pr checkout <pr-number>

Create/Update PR (REQUIRES APPROVAL)

bash

# Create PR - ASK APPROVAL FIRST
gh pr create --title "Add feature X" --body "Description..."

# Add comment - ASK APPROVAL FIRST
gh pr comment <pr-number> --body "LGTM!"

# Merge PR - ASK APPROVAL FIRST
gh pr merge <pr-number> --squash

Debugging CI/CD Failures

Quick Diagnosis Workflow

bash

# 1. List recent failed runs
gh run list --status failure --limit 10

# 2. Get details of failed run
gh run view <run-id>

# 3. View failed job logs
gh run view <run-id> --log-failed

# 4. Get specific job details
gh run view <run-id> --json jobs --jq '.jobs[] | select(.conclusion=="failure")'

# 5. View step-by-step failure
gh run view <run-id> --json jobs --jq '.jobs[] | select(.conclusion=="failure") | .steps[] | select(.conclusion=="failure") | {name, conclusion}'

Common Patterns

bash

# Check if main branch is green
gh run list --branch main --limit 1 --json conclusion -q '.[0].conclusion'

# Find flaky tests
gh run list --workflow test.yml --limit 50 --json conclusion,headBranch | jq 'group_by(.headBranch) | .[] | select(length > 1)'

Output Formatting

bash

# JSON output (for jq processing)
gh issue list --json number,title,state

# Specific field with jq
gh pr view 123 --json reviews --jq '.reviews[].state'

# Table format
gh issue list --json number,title,state --jq '.[] | [.number, .title, .state] | @tsv'

Troubleshooting

Issue	Cause	Fix
"Not authenticated"	gh not logged in	`gh auth login`
"Repository not found"	Wrong repo context	Use `--repo owner/repo` or `gh repo set-default`
"No workflows found"	Missing workflow files	Check `.github/workflows/` exists
"Permission denied"	Insufficient token scope	Re-auth with `gh auth login`
"Rate limit exceeded"	Too many API calls	Wait or authenticate for higher limits
Command hangs	Interactive prompt expected	Add `--yes` flag or provide all required args

Example Requests

User Request	Action
"Why is CI failing?"	`gh run list --status failure`, then `gh run view <id> --log-failed`
"Check my PR status"	`gh pr checks <number>` or `gh pr view <number>`
"List open issues"	`gh issue list`
"What PRs need my review?"	`gh pr list --search "review-requested:@me"`
"Merge PR 123"	Ask approval, then `gh pr merge 123 --squash`
"Create an issue for this bug"	Ask approval, then `gh issue create --title "..." --body "..."`
"Rerun the failed tests"	Ask approval, then `gh run rerun <id> --failed`

Safety Checklist

Before ANY state-changing operation:

• Is this a read-only command? If yes, proceed.
• Have I asked the user for explicit approval?
• Did the user say "yes" or approve the specific command?
• Verified correct repository context
• Understood the impact (what will be created/modified/deleted)

State-Changing Commands Summary

Category	Commands Requiring Approval
Workflows	`run rerun`, `workflow run`
Issues	`issue create`, `issue close`, `issue edit`, `issue comment`, `issue reopen`
PRs	`pr create`, `pr merge`, `pr close`, `pr edit`, `pr comment`, `pr review`, `pr ready`
Labels	`label create`, `label edit`, `label delete`
Projects	`project item-add`