GitHub CLI Workflow
Use gh when a task needs local GitHub operations from the checkout: PR
creation, PR updates, checks, reviews, comments, Actions runs, issues, or repo
metadata. Prefer gh over hand-written REST calls when the user explicitly asks
for gh or when a connector cannot perform a write that local credentials can.
Find Or Install gh
Check the current shell:
gh --version
Get-Command gh -All -ErrorAction SilentlyContinue
On Windows, also check the installed absolute path because PATH may be stale:
Test-Path "$env:ProgramFiles\GitHub CLI\gh.exe"
& "$env:ProgramFiles\GitHub CLI\gh.exe" --version
If missing and winget is available, install GitHub CLI:
winget show --id GitHub.cli -e --source winget
winget install --id GitHub.cli -e --source winget --accept-package-agreements --accept-source-agreements --silent
After install, use the absolute path if the current shell still cannot find
gh through PATH.
Authentication
Check auth before writes:
& "$env:ProgramFiles\GitHub CLI\gh.exe" auth status
If not authenticated, ask the user to complete gh auth login in a visible
browser flow. Never print tokens. Avoid gh auth token unless piping it
directly into another command without echoing it.
Publish A PR
Inspect state before branch, commit, rebase, push, or PR creation:
git status --short --branch
git branch --show-current
git log --oneline --decorate --max-count=5
Preserve unrelated dirty files. Stage explicit pathspecs, commit intended
changes, and push the current branch:
git push -u origin "$(git branch --show-current)"
Discover repo and default branch:
gh repo view --json nameWithOwner,defaultBranchRef,url
Check for an existing PR before creating a new one:
gh pr list --head "$(git branch --show-current)" --state all --json number,url,state,title,isDraft,headRefName,baseRefName
Create a ready PR by default unless the user asks for draft. Use a temp body
file so Markdown renders correctly:
$body = New-TemporaryFile
Set-Content -Encoding UTF8 $body @'
## Summary
- ...
## Validation
- ...
'@
gh pr create --base main --head "$(git branch --show-current)" --title "Add content publishing workflow" --body-file $body
Use --draft only when requested. Do not use --fill if commit messages would
produce a noisy or incomplete PR body.
Inspect PRs, Comments, And CI
Use these after every push:
gh pr view <number> --json number,url,state,isDraft,headRefName,baseRefName,mergeStateStatus,statusCheckRollup,reviews,latestReviews,comments
gh api repos/<owner>/<repo>/pulls/<number>/comments
gh pr checks <number> --watch --interval 10
For Copilot or inline-review gates, inspect both review submissions and pull
request review comments. Treat connector or web UI summaries as insufficient
when the repository workflow requires explicit comment/thread checks.
Common Failures
gh not recognized after install: call
C:\Program Files\GitHub CLI\gh.exe directly or start a fresh shell.- Connector PR creation returns
must be a collaborator: use gh pr create
with the already-pushed branch and authenticated local account.
- Existing merged PR used the same old head branch: create and push a fresh
branch name from the current commit, then run
gh pr create with that head.
- Dirty worktree blocks rebase/switch: inspect the diff; commit intended changes
or leave unrelated changes untouched and choose a non-destructive path.
1---2name: gh-workflow3description: Use GitHub CLI (`gh`) for local GitHub workflows such as installing or locating gh on Windows, checking authentication, creating or updating pull requests, inspecting PR reviews/comments/checks, monitoring CI, and falling back from GitHub connector failures such as "must be a collaborator" when a pushed branch can be published with gh.4---56# GitHub CLI Workflow78Use `gh` when a task needs local GitHub operations from the checkout: PR9creation, PR updates, checks, reviews, comments, Actions runs, issues, or repo10metadata. Prefer `gh` over hand-written REST calls when the user explicitly asks11for `gh` or when a connector cannot perform a write that local credentials can.1213## Find Or Install `gh`14151. Check the current shell:1617 ```powershell18 gh --version19 Get-Command gh -All -ErrorAction SilentlyContinue20 ```21222. On Windows, also check the installed absolute path because PATH may be stale:2324 ```powershell25 Test-Path "$env:ProgramFiles\GitHub CLI\gh.exe"26 & "$env:ProgramFiles\GitHub CLI\gh.exe" --version27 ```28293. If missing and `winget` is available, install GitHub CLI:3031 ```powershell32 winget show --id GitHub.cli -e --source winget33 winget install --id GitHub.cli -e --source winget --accept-package-agreements --accept-source-agreements --silent34 ```35364. After install, use the absolute path if the current shell still cannot find37 `gh` through PATH.3839## Authentication4041Check auth before writes:4243```powershell44& "$env:ProgramFiles\GitHub CLI\gh.exe" auth status45```4647If not authenticated, ask the user to complete `gh auth login` in a visible48browser flow. Never print tokens. Avoid `gh auth token` unless piping it49directly into another command without echoing it.5051## Publish A PR52531. Inspect state before branch, commit, rebase, push, or PR creation:5455 ```powershell56 git status --short --branch57 git branch --show-current58 git log --oneline --decorate --max-count=559 ```60612. Preserve unrelated dirty files. Stage explicit pathspecs, commit intended62 changes, and push the current branch:6364 ```powershell65 git push -u origin "$(git branch --show-current)"66 ```67683. Discover repo and default branch:6970 ```powershell71 gh repo view --json nameWithOwner,defaultBranchRef,url72 ```73744. Check for an existing PR before creating a new one:7576 ```powershell77 gh pr list --head "$(git branch --show-current)" --state all --json number,url,state,title,isDraft,headRefName,baseRefName78 ```79805. Create a ready PR by default unless the user asks for draft. Use a temp body81 file so Markdown renders correctly:8283 ```powershell84 $body = New-TemporaryFile85 Set-Content -Encoding UTF8 $body @'86 ## Summary8788 - ...8990 ## Validation9192 - ...93 '@94 gh pr create --base main --head "$(git branch --show-current)" --title "Add content publishing workflow" --body-file $body95 ```9697Use `--draft` only when requested. Do not use `--fill` if commit messages would98produce a noisy or incomplete PR body.99100## Inspect PRs, Comments, And CI101102Use these after every push:103104```powershell105gh pr view <number> --json number,url,state,isDraft,headRefName,baseRefName,mergeStateStatus,statusCheckRollup,reviews,latestReviews,comments106gh api repos/<owner>/<repo>/pulls/<number>/comments107gh pr checks <number> --watch --interval 10108```109110For Copilot or inline-review gates, inspect both review submissions and pull111request review comments. Treat connector or web UI summaries as insufficient112when the repository workflow requires explicit comment/thread checks.113114## Common Failures115116- `gh` not recognized after install: call117 `C:\Program Files\GitHub CLI\gh.exe` directly or start a fresh shell.118- Connector PR creation returns `must be a collaborator`: use `gh pr create`119 with the already-pushed branch and authenticated local account.120- Existing merged PR used the same old head branch: create and push a fresh121 branch name from the current commit, then run `gh pr create` with that head.122- Dirty worktree blocks rebase/switch: inspect the diff; commit intended changes123 or leave unrelated changes untouched and choose a non-destructive path.
eunomia-bpf