GitHub

GitHub

Use this skill whenever the task involves GitHub and the gh CLI is available or should be made available. Prefer direct gh commands over browser-only workflows for operations that have stable CLI support.

Typical Goals

• Inspect, create, update, label, assign, or close issues.
• Inspect, create, checkout, review, comment on, merge, or monitor pull requests.
• Check GitHub Actions runs, jobs, failed logs, and commit statuses.
• Query repository metadata, branches, tags, releases, artifacts, and security or Dependabot alerts when permissions allow.
• Use gh api or GraphQL for fields not exposed by first-class subcommands.
• Install or authenticate gh on a persistent VM when the user needs reusable GitHub CLI access.

Operating Principles

• Use --repo owner/name when outside the target repository or when ambiguity is possible.
• Prefer --json with --jq for machine-readable output instead of parsing tables.
• Prefer managed OAuth over device-flow setup. When GitHub credentials are missing, expired, or insufficient, use RequestOAuthAuthorization to connect the user's GitHub account, then pass the saved credential to Exec.credential_env.
• Confirm destructive or hard-to-reverse actions before running them unless the user explicitly requested the action.
• Do not claim an issue, PR, workflow, or release was changed until the CLI command succeeds.
• If auth or permissions fail, report the concrete blocker and the command that exposed it.
• Keep generated issue and PR text concise and specific; avoid adding unrelated templates or markdown documents unless asked.

Managed OAuth

Before running a device-flow login or asking the user for a token, check whether a GitHub OAuth credential already exists:

1. Call ListOAuthCredentials.
2. If a github credential is available and active, use its alias in Exec.credential_env; replace "default" below with the actual alias returned by ListOAuthCredentials:

   [{"env_var":"GH_TOKEN","provider":"github","alias":"default","value":"access_token"}]

3. If no usable GitHub credential exists, call RequestOAuthAuthorization with provider: "github", a short stable alias such as "default", and a concise reason. Request scopes that match the task, for example ["repo"] for private repository read/write, ["read:org"] for organization metadata, and ["workflow"] only when workflow file changes or Actions operations require it.
4. Share the returned authorization_url with the user and wait for them to confirm they completed authorization.
5. Call CompleteOAuthAuthorization with the returned state. If it returns completed, retry the GitHub command with Exec.credential_env using the returned alias. If it returns pending, ask the user to finish the browser flow. If it returns failed or expired, start a fresh authorization flow.

Managed OAuth keeps tokens out of the transcript. Do not print the token or try to read it directly; inject it only for the subprocess that needs GitHub access. gh honors GH_TOKEN, so a full gh auth login is usually unnecessary when using this flow.

Initial Checks

gh --version
gh auth status -h github.com
git remote -v

When the repository is known:

gh repo view owner/name --json nameWithOwner,defaultBranchRef,viewerPermission

Issues

Search issues:

gh issue list --repo owner/name --search "login timeout session expired" --json number,title,state,url,labels,updatedAt

View an issue:

gh issue view 123 --repo owner/name --json number,title,body,state,url,labels,assignees,comments

Create an issue:

gh issue create --repo owner/name --title "Investigate login timeout on macOS" --body "..."

Update or comment:

gh issue edit 123 --repo owner/name --add-label bug --add-assignee @me
gh issue comment 123 --repo owner/name --body "..."

Pull Requests

List and view PRs:

gh pr list --repo owner/name --state open --json number,title,author,headRefName,baseRefName,isDraft,reviewDecision,statusCheckRollup
gh pr view 55 --repo owner/name --json number,title,body,state,url,files,commits,reviews,comments

Check out a PR when code inspection is needed:

gh pr checkout 55 --repo owner/name

Create or update a PR:

gh pr create --repo owner/name --base main --head feature-branch --title "Title" --body "..."
gh pr edit 55 --repo owner/name --title "New title" --body "..."

Review, comment, and merge:

gh pr review 55 --repo owner/name --comment --body "..."
gh pr review 55 --repo owner/name --approve --body "..."
gh pr merge 55 --repo owner/name --squash --delete-branch

Use the repository's merge policy and user instructions when choosing merge mode.