Lap Tran
a35c0bb744
- Symlink ~/.config/opencode/opencode.json and skills/ from dotfiles so opencode 1.x config survives rebuild with zap cleanup - Track cloud-deploy, cloudflared, github-cli, no-mistakes, playwright-cli, and read-tweet skills in repo - Update opencode2 model to opencode/muse-spark-1.2-contributor-free - Rotate opencode.json/skills in rebuild.sh alongside existing managed paths
136 lines
4.5 KiB
Markdown
136 lines
4.5 KiB
Markdown
---
|
|
name: github-cli
|
|
description: Use when the user asks to open a PR, review or merge a PR, list/check/review issues, react to or comment on PRs, create/manage releases, browse a repo's metadata, or do any GitHub operation without opening the web UI. Triggers on keywords like "gh", "GitHub CLI", "open a PR", "merge the PR", "review request", "list my PRs", "create release". Installs and drives the `gh` CLI so the agent never needs the browser for GitHub workflows.
|
|
---
|
|
|
|
# GitHub CLI (`gh`) — GitHub without the web UI
|
|
|
|
The agent should open PRs, review, merge, and manage issues/releases from the terminal instead of telling the user to "go to GitHub and click merge."
|
|
|
|
## Install (first use)
|
|
|
|
If `gh` is not on PATH:
|
|
|
|
```bash
|
|
brew install gh # macOS
|
|
# or: sudo apt install gh # Debian/Ubuntu
|
|
# or: winget install GitHub.cli # Windows
|
|
```
|
|
|
|
Authenticate (one-time):
|
|
|
|
```bash
|
|
gh auth login
|
|
# choose GitHub.com → HTTPS → "Login with a web browser"
|
|
# or use a token: echo "$GH_TOKEN" | gh auth login --with-token
|
|
```
|
|
|
|
Verify: `gh auth status`.
|
|
|
|
If automation is needed and interactive login isn't possible, set `GH_TOKEN` (or `GITHUB_TOKEN`) env var from a fine-grained PAT with the repo scopes needed (contents, pull-requests, workflows, issues).
|
|
|
|
## Core workflows
|
|
|
|
### Open a PR from the current branch
|
|
|
|
```bash
|
|
gh pr create --title "<title>" --body "<body>" --base main
|
|
# body supports markdown; can also read from a file: --body-file pr.md
|
|
# add reviewers/assignees/labels:
|
|
gh pr create --title "..." --body "..." --reviewer alice,bob --label "needs review" --assignee @me
|
|
```
|
|
|
|
The opencode convention: only open PRs when the user explicitly asks. Inspect `git status`, `git diff`, and `git log --oneline -10` first, and stage only intended files.
|
|
|
|
### Review and merge
|
|
|
|
```bash
|
|
gh pr view <N> # PR details, checks, mergeable state
|
|
gh pr view <N> --comments # read the discussion
|
|
gh pr diff <N> # the diff in the terminal
|
|
gh pr checks <N> # CI status
|
|
gh pr review <N> --approve --body "lgtm"
|
|
gh pr review <N> --request-changes --body "please fix X"
|
|
gh pr merge <N> --squash --delete-branch
|
|
# --merge / --squash / --rebase match repo allowed methods
|
|
# --auto waits for required checks before merging
|
|
```
|
|
|
|
### List and filter
|
|
|
|
```bash
|
|
gh pr list --author @me --state open
|
|
gh pr list --search "review-requested:@me"
|
|
gh issue list --assignee @me --state open
|
|
gh pr list --state closed --limit 5
|
|
```
|
|
|
|
### Issues
|
|
|
|
```bash
|
|
gh issue create --title "..." --body "..." --label bug --assignee @me
|
|
gh issue view <N>
|
|
gh issue close <N>
|
|
gh issue comment <N> --body "..."
|
|
```
|
|
|
|
### Releases
|
|
|
|
```bash
|
|
gh release create v1.2.3 --notes "..." --title "v1.2.3"
|
|
gh release create v1.2.3 ./dist/* # attach build artifacts
|
|
gh release list
|
|
gh release view v1.2.3
|
|
gh release download v1.2.3
|
|
```
|
|
|
|
### Repo metadata & browsing
|
|
|
|
```bash
|
|
gh repo view # current repo info
|
|
gh repo view owner/repo # another repo
|
|
gh repo clone owner/repo
|
|
gh repo create <name> --private --source=. --push # create + push cwd
|
|
gh repo fork owner/repo --clone
|
|
```
|
|
|
|
### Cross-repo / search
|
|
|
|
```bash
|
|
gh search prs --author @me --state open
|
|
gh search issues "is:open label:bug"
|
|
gh search repos "topic:local-llm"
|
|
```
|
|
|
|
## Aliases (optional quality-of-life)
|
|
|
|
```bash
|
|
gh alias set co 'pr checkout'
|
|
gh alias set rv 'pr review --view'
|
|
# then: gh co 123 → gh pr checkout 123
|
|
```
|
|
|
|
## When to use
|
|
|
|
- "Open a PR for this branch" / "merge it" / "what's the status of PR #123"
|
|
- "Review the latest PR" / "request changes on #45"
|
|
- "List my open issues" / "create an issue for this bug"
|
|
- "Cut a release" / "attach these binaries to v2.0"
|
|
- Any GitHub action where the agent would otherwise say "go to the web UI"
|
|
|
|
## When NOT to use
|
|
|
|
- Reading the repo's source code → use Read/Glob/Grep on the working copy, not `gh`
|
|
- Git operations (commit, push, branch) → use `git` directly; `gh` wraps GitHub, not git
|
|
- Long-form PR body authoring → write to a file first, pass `--body-file`
|
|
|
|
## Auth troubleshooting
|
|
|
|
- `gh auth status` fails → run `gh auth login` again, or confirm `GH_TOKEN` is exported in the shell.
|
|
- "could not find any releases" on a fork → releases live on the upstream repo; use `gh release list --repo owner/repo`.
|
|
- 403 on merge → the token lacks `pull-requests: write` (or repo `contents: write`); regenerate with the scope and re-login.
|
|
|
|
## Source
|
|
|
|
Referenced in https://x.com/heyshruti7/status/2069083108092350823 — "GitHub CLI — open PRs, review, merge. Your agent never touches the web UI."
|