---
name: github-workflows
description: GitHub CLI (gh + git) delegation workflows — auth, PRs, code review, issues, repo management. Load this when delegating any GitHub task to a subagent or running gh/git directly.
version: 1.0.0
category: github
tags: [github, gh, git, pr, code-review, issues, delegation]
---

# GitHub Workflows

Omnibus skill covering all GitHub CLI delegation patterns. Sub-sections below cover each domain.

> Absorbed from: github-auth, github-code-review, github-issues, github-pr-workflow, github-repo-management, codex (GitHub PR delegation aspect).

---

## 1. Authentication — github-auth

**Trigger:** Setup, token rotation, SSH key configuration, gh CLI login.

### HTTPS token setup
```bash
gh auth login --hostname github.com --token <TOKEN>
```
Or manually: add to `~/.netrc`:
```
machine github.com
  login <username>
  password <TOKEN>
```

### SSH key setup
```bash
# Generate Ed25519 (preferred)
ssh-keygen -t ed25519 -C "hermes@lfcs" -f ~/.ssh/id_github_ed25519
# Add to GitHub: Settings → SSH keys → New key
```

### gh CLI auth check
```bash
gh auth status
```

### Token scopes needed
| Task | Scope |
|---|---|
| Read repos | `repo` (full) or `repo:read` |
| Write issues/PRs | `repo` |
| Actions | `workflow` |
| Packages | `package:read` |

---

## 2. PR Lifecycle — github-pr-workflow

**Trigger:** "review this PR", "open a PR", "check CI status", "merge".

### Open a PR
```bash
gh pr create --title "..." --body "..." --base main --reviewer @me
```

### List PRs
```bash
gh pr list --state=open --limit 20
gh pr list --state=merged --limit 10
```

### View diff
```bash
gh pr diff <PR-NUMBER>
```

### Approve / Comment
```bash
gh pr review <PR-NUMBER> --approve -b "LGTM"
gh pr review <PR-NUMBER> --comment -b "nit: ..."
```

### Merge
```bash
gh pr merge <PR-NUMBER> --squash --delete-branch
```

### CI status
```bash
gh pr check-runs <PR-NUMBER>
```

---

## 3. Code Review — github-code-review

**Trigger:** "review this PR", "what changed", "inline comment".

### Full review workflow
```bash
# 1. Fetch PR
gh pr checkout <PR-NUMBER>

# 2. View changed files
gh pr diff <PR-NUMBER> --name-only

# 3. Full diff
gh pr diff <PR-NUMBER>

# 4. Post review
gh pr review <PR-NUMBER> --approve --comment -b "..."
```

### Inline comments via REST
```bash
# Get PR commit SHA
COMMIT_SHA=$(gh api repos/{owner}/{repo}/pulls/<PR-NUMBER> --jq '.head.sha')

# Create review comment
gh api repos/{owner}/{repo}/pulls/<PR-NUMBER}/comments \
  --method POST \
  --field body="..." \
  --field path=<file> \
  --field line=<line> \
  --field side=RIGHT \
  --field commit_id=$COMMIT_SHA
```

### Review summary
```bash
gh pr view <PR-NUMBER> --json title,body,state,additions,deletions,changedFiles
```

---

## 4. Issues — github-issues

**Trigger:** "create an issue", "list issues", "label", "assign".

### Create
```bash
gh issue create --title "..." --body "..." --label bug --assignee @me
```

### List
```bash
gh issue list --state=open --limit 50
gh issue list --state=closed --since 2024-01-01
```

### Label
```bash
gh issue edit <ISSUE-NUMBER> --add-label bug --remove-label enhancement
```

### Close with comment
```bash
gh issue close <ISSUE-NUMBER> --comment "Fixed in ..."
```

### Bulk operations via REST
```bash
# Add label to multiple issues
for id in 42 43 44; do
  gh api repos/{owner}/{repo}/issues/$id/labels \
    --method POST \
    --field name=priority
done
```

---

## 5. Repo Management — github-repo-management

**Trigger:** Clone, fork, manage remotes, releases, tags.

### Clone
```bash
gh repo clone {owner}/{repo}
# or
git clone https://github.com/{owner}/{repo}.git
```

### Fork + clone
```bash
gh repo fork {owner}/{repo} --clone
```

### Add remote
```bash
git remote add <name> https://github.com/{owner}/{repo}.git
```

### Releases
```bash
gh release list
gh release create v1.0.0 --title "Release v1.0.0" --notes "..."
gh release download v1.0.0 -p ./artifacts/
```

### Archive repo
```bash
gh repo archive <OWNER>/<REPO> --yes
```

---

## 6. Delegation to Codex — codex (GitHub PR aspect)

**Trigger:** Delegate a full GitHub PR review or update to Codex CLI.

```bash
# Run Codex on a PR review
codex --model claude-sonnet-4 "Review PR #<NUMBER> in {owner}/{repo}. Focus on: correctness, security, test coverage."

# Run Codex on a code review task
codex --model claude-sonnet-4 "List all open PRs in {owner}/{repo}, summarize changes, flag any that need attention."
```

See `codex` skill for full invocation patterns. This sub-section covers only the GitHub integration layer.

---

## Pitfalls

1. **gh auth token expired** — `gh auth status` shows it. Re-run `gh auth login`.
2. **SSH key not added to gh** — use `ssh-agent` or set `GIT_SSH_COMMAND`.
3. **Merge conflict** — `gh pr checkout <PR>` then resolve locally, push.
4. **Large PR diff** — use `--limit` or `--json` to filter; don't pipe full diff to terminal.
5. **PR not found** — check you're on the right repo: `gh repo view`.