gh-cli

name	gh-cli
description	Use this skill whenever a task involves GitHub CLI (gh): running GitHub operations, translating GitHub tasks into gh syntax, code search, Actions failure triage, Pages deployment, security publishing (SARIF/check-run/issue), secret scanning, Discussions GraphQL reads, deterministic branch creation from a base SHA, or sub-issue mutations. Prefer native gh for simple one-step operations, and use this skill's wrapper-based workflows for multi-step, validation-heavy, or deterministic machine-output tasks. Do not under-trigger this skill when gh is likely involved.
license	MPL-2.0
compatibility	observed GitHub CLI v2.89.0
metadata	{"author":"James Prial (@JamesPrial), Arjun Pramanik (@capybearista)","version":"3.0.0"}

GitHub CLI (gh)

Overview

Use this skill for GitHub automation through native gh commands first, then wrapper scripts for high-friction flows that require strict validation, normalized output, or multi-step orchestration.

This skill assumes:

• gh is installed and authenticated (gh auth status)
• Python 3 is available for wrapper scripts
• commands are run from repository root unless stated otherwise

Operating Model

1. Prefer native gh for standard operations.
2. Use wrapper scripts for complex workflows, deterministic envelopes, and stricter input contracts.
3. Keep outputs machine-consumable where possible (--json, wrapper JSON envelopes).
4. Use references in references/ for full per-script contracts.

GitHub CLI Command Guide (Native First)

Use these patterns for routine work before reaching for wrappers.

Authentication and Context

gh auth status
gh repo view --json nameWithOwner,defaultBranchRef,isPrivate
gh repo set-default OWNER/REPO

Repository and Branch Operations

gh repo clone OWNER/REPO
gh repo fork OWNER/REPO --clone
gh api repos/OWNER/REPO/git/ref/heads/main
gh api repos/OWNER/REPO/git/refs -f ref='refs/heads/feature/x' -f sha='<sha>'

Pull Requests and Issues

gh pr list --state open --json number,title,headRefName,baseRefName
gh pr view <number> --json title,body,mergeStateStatus,reviewDecision
gh pr create --title "..." --body "..."
gh issue list --state open --json number,title,labels,assignees
gh issue create --title "..." --body "..."

Actions and Workflow Inspection

gh run list --limit 20 --json databaseId,workflowName,headBranch,status,conclusion,createdAt
gh run view <run-id> --json jobs,conclusion,status,url
gh run view <run-id> --log
gh workflow list
gh workflow view <name-or-id>

Discussions and Search

gh api graphql -f query='query { viewer { login } }'
gh search code "TODO repo:OWNER/REPO" --json repository,path,textMatches

Pages, Security, and Low-Level API Usage

gh api repos/OWNER/REPO/pages
gh api repos/OWNER/REPO/pages --method POST -f build_type=workflow
gh api repos/OWNER/REPO/check-runs --method POST -F name='Security Scan' -F head_sha='<sha>'
gh api repos/OWNER/REPO/code-scanning/sarifs --method POST -f commit_sha='<sha>' -f ref='refs/heads/main' -f sarif='...'

Core Capabilities (Wrapper Scripts)

1. Common Wrapper Contract

Use scripts/gh_wrapper_common.py for shared envelope, validation, and error normalization behavior across wrappers.

Key features: standard success/failure JSON envelope, error classification, owner/repo validation helpers, normalized command execution.

Documentation: references/README_gh_wrapper_common.md

2. Enhanced Code Search

Use scripts/gh_code_search.py when native gh search code needs extra filtering, formatting, and deterministic sorting.

Key features: local post-filters (--exclude-forks, --exclude-private, --min-matches), output modes, deterministic sorting.

Documentation: references/README_gh_code_search.md

3. Workflow Failure Analysis

Use scripts/gh_failed_run.py to extract actionable failure details from failed workflow runs.

Key features: failed run targeting, failed job extraction, redacted error excerpts for safer output.

Documentation: references/README_gh_failed_run.md

4. GitHub Pages Management

Use scripts/gh_pages_deploy.py to enable Pages, inspect status, trigger rebuilds, and generate starter workflows.

Key features: enable/status/rebuild/create-workflow flows, deterministic handling for workflow build-type rebuild incompatibility.

Documentation: references/README_gh_pages_deploy.md

5. Security Findings Publication

Use scripts/gh_security_emit.py to publish precomputed findings as sarif, check-run, or issue.

Key features: strict mode contracts, schema validation, native endpoint first with fallback transport support when auth/capability blocks direct check-run or SARIF submission.

Documentation: references/README_gh_security_emit.md

6. Secret Scanning

Use scripts/gh_secret_scan.py to scan refs/commits/diffs/local paths for potential secret patterns.

Key features: target-selector enforcement, severity thresholding, masked findings, optional SARIF artifact generation.

Documentation: references/README_gh_secret_scan.md

7. Discussions Bridge

Use scripts/gh_discussions_bridge.py for normalized GraphQL reads of discussions data.

Key features: list|get|comments|categories method contracts, deterministic pagination envelope, method/flag validation.

Documentation: references/README_gh_discussions_bridge.md

8. Branch Creation from Base

Use scripts/gh_branch_create_from_base.py to resolve base SHA and create a new branch ref deterministically.

Key features: base ref resolution, branch ref creation, dry-run mode with same envelope shape.

Documentation: references/README_gh_branch_create_from_base.md

9. Sub-Issue Mutations

Use scripts/gh_subissue_bridge.py for add, remove, and reprioritize-after sub-issue operations.

Key features: issue number to node ID resolution, strict action contracts, validation-first mutation workflow.

Documentation: references/README_gh_subissue_bridge.md

Wrapper Behavior Expectations

Wrappers using gh_wrapper_common.py emit a standard envelope:

• success: ok=true, version, operation, data, meta.duration_ms
• failure: ok=false, version, operation, error, meta.duration_ms

Common exit intent:

• 0 success
• 1 runtime/validation class failure
• 2 auth/permission class failure
• 3 API class failure

Decision Rules: Native gh vs Wrapper

Use native gh when:

• the task is a straightforward single command
• built-in --json output is enough
• no cross-command orchestration is needed

Use wrappers when:

• strict input validation is needed before API calls
• deterministic output envelope is required
• flow spans multiple calls (resolve, transform, publish)
• fallback behavior is required for environment constraints

Important Script-Specific Guidance

• gh_security_emit.py: attempt native check-run/SARIF publish first; if blocked by auth/capability, allow fallback transport and report transport metadata clearly.
• gh_pages_deploy.py: for workflow-build-type repositories, treat known rebuild endpoint 403/404 incompatibility as deterministic skip, not ambiguous failure.
• gh_secret_scan.py: treat findings as masked indicators only; do not print raw secret values.

Quick Usage

python3 skills/gh-cli/scripts/gh_code_search.py --help
python3 skills/gh-cli/scripts/gh_failed_run.py --help
python3 skills/gh-cli/scripts/gh_pages_deploy.py --help
python3 skills/gh-cli/scripts/gh_security_emit.py --help
python3 skills/gh-cli/scripts/gh_secret_scan.py --help
python3 skills/gh-cli/scripts/gh_discussions_bridge.py --help
python3 skills/gh-cli/scripts/gh_branch_create_from_base.py --help
python3 skills/gh-cli/scripts/gh_subissue_bridge.py --help
python3 skills/gh-cli/scripts/test_wrapper_scripts.py --help