---
name: github
description: "GitHub workflow: auth setup, PR lifecycle, code review, issue management, repo operations. Covers gh CLI and curl fallbacks."
version: 1.0.0
author: Hermes Agent
license: MIT
platforms: [linux, macos, windows]
metadata:
  hermes:
    tags: [GitHub, Git, Pull-Requests, Code-Review, Issues, Repositories, gh-cli]
---

# GitHub Workflow — Complete Guide

End-to-end GitHub operations: authentication, repository management, PR lifecycle, code review, and issue tracking. Every section shows `gh` CLI first, then `git` + `curl` fallback for machines without `gh`.

## Quick Auth Check

Run this at the start of any GitHub workflow:

```bash
if command -v gh &>/dev/null && gh auth status &>/dev/null; then
  echo "AUTH_METHOD=gh"
elif [ -n "$GITHUB_TOKEN" ]; then
  echo "AUTH_METHOD=curl"
elif grep -q "github.com" ~/.git-credentials 2>/dev/null; then
  export GITHUB_TOKEN=$(grep "github.com" ~/.git-credentials | head -1 | sed 's|https://[^:]*:\([^@]*\)@.*|\1|')
  echo "AUTH_METHOD=curl"
else
  echo "AUTH_METHOD=none — need to set up auth first"
fi
```

See `references/auth.md` for complete auth setup (HTTPS tokens, SSH keys, gh CLI login, troubleshooting).

## Operations Overview

| Task | Reference | Key Commands |
|------|-----------|-------------|
| **Auth setup** | `references/auth.md` | `gh auth login`, SSH keys, credential helpers |
| **Repo management** | `references/repo-management.md` | clone, create, fork, releases, secrets, Actions |
| **PR lifecycle** | `references/pr-workflow.md` | branch, commit, open, CI monitoring, merge |
| **Code review** | `references/code-review.md` | local diff review, PR comments, inline review, submit review |
| **Issue management** | `references/issues.md` | create, triage, label, assign, bulk operations |
| **Codebase inspection** | `references/codebase-inspection.md` | LOC counts, language breakdown, code-vs-comment ratios via pygount |

## Common Patterns

### Creating a Feature PR (end-to-end)
1. Branch: `git checkout -b feat/description`
2. Commit with conventional format: `feat(scope): description`
3. Push: `git push -u origin HEAD`
4. Open PR: `gh pr create --title "..." --body "..."`
5. Monitor CI: `gh pr checks --watch`
6. Merge: `gh pr merge --squash --delete-branch`

See `references/pr-workflow.md` for the complete lifecycle with CI auto-fix loops.

### Reviewing a PR
1. Get PR context: `gh pr view N` + `gh pr diff N --name-only`
2. Check out locally: `git fetch origin pull/N/head:pr-N && git checkout pr-N`
3. Read diff + full files with `read_file`
4. Apply review checklist (correctness, security, quality, testing, performance)
5. Submit: `gh pr review N --approve|--request-changes|--comment`

See `references/code-review.md` for inline comments, formal reviews, and the review checklist.

### Triaging Issues
1. List untriaged: `gh issue list --label "needs-triage"`
2. Categorize and apply labels
3. Assign if owner is clear
4. Comment with triage notes

See `references/issues.md` for templates, bulk operations, and linking issues to PRs.

## Support Files

### References
- `references/auth.md` — Full authentication setup and troubleshooting
- `references/repo-management.md` — Clone, create, fork, settings, releases, secrets, Actions, gists
- `references/pr-workflow.md` — Branch creation, commits, CI monitoring, auto-fix, merging
- `references/code-review.md` — Local review, PR review, inline comments, formal review submission
- `references/issues.md` — Create, manage, triage, bulk operations
- `references/conventional-commits.md` — Commit message format conventions
- `references/ci-troubleshooting.md` — Diagnosing and fixing CI failures
- `references/review-output-template.md` — Structured review output format
- `references/github-api-cheatsheet.md` — GitHub REST API endpoint quick reference

### Templates
- `templates/bug-report.md` — Bug report issue template
- `templates/feature-request.md` — Feature request issue template
- `templates/pr-body-bugfix.md` — PR body template for bug fixes
- `templates/pr-body-feature.md` — PR body template for features

### Scripts
- `scripts/gh-env.sh` — Source this to set up GitHub auth env vars in shell
