---
name: github
description: "GitHub operations via gh CLI and git+curl: auth, repos, PRs, issues, code review, releases, Actions."
version: 2.0.0
author: Hermes Agent
license: MIT
platforms: [linux, macos, windows]
metadata:
  hermes:
    tags: [GitHub, Git, gh-cli, Pull-Requests, Issues, Code-Review, Repositories, CI/CD, Releases]
    related_skills: [code-editing, requesting-code-review]
---

# GitHub Operations

Complete guide for working with GitHub via `gh` CLI (preferred) or `git` + `curl` (fallback). All sections share the same auth detection and repo context extraction.

## Quick Start — Auth Detection

Run this at the start of any GitHub workflow:

```bash
if command -v gh &>/dev/null && gh auth status &>/dev/null; then
  AUTH="gh"
else
  AUTH="git"
  if [ -z "$GITHUB_TOKEN" ]; then
    if [ -f ~/.hermes/.env ] && grep -q "^GITHUB_TOKEN=" ~/.hermes/.env; then
      GITHUB_TOKEN=$(grep "^GITHUB_TOKEN=" ~/.hermes/.env | head -1 | cut -d= -f2 | tr -d '\n\r')
    elif grep -q "github.com" ~/.git-credentials 2>/dev/null; then
      GITHUB_TOKEN=$(grep "github.com" ~/.git-credentials 2>/dev/null | head -1 | sed 's|https://[^:]*:\([^@]*\)@.*|\1|')
    fi
  fi
fi
```

## Quick Start — Owner/Repo Extraction

```bash
REMOTE_URL=$(git remote get-url origin)
OWNER_REPO=$(echo "$REMOTE_URL" | sed -E 's|.*github\.com[:/]||; s|\.git$||')
OWNER=$(echo "$OWNER_REPO" | cut -d/ -f1)
REPO=$(echo "$OWNER_REPO" | cut -d/ -f2)
```

---

## Section 1: Authentication Setup

Full auth setup instructions when the above detection returns `AUTH=none`.

See `references/github-auth.md` for the complete auth guide covering HTTPS tokens, SSH keys, and gh CLI login.

### Token Setup (Quick Path)

1. Generate token at **https://github.com/settings/tokens** (scopes: `repo`, `workflow`, `read:org`)
2. Configure git: `git config --global credential.helper store`
3. Test: `git ls-remote https://github.com/<user>/<repo>.git`

---

## Section 2: Repository Management

Clone, create, fork, configure repos, manage releases, and Actions.

### Quick Reference

| Action | gh | git + curl |
|--------|-----|-----------|
| Clone | `gh repo clone o/r` | `git clone https://github.com/o/r.git` |
| Create repo | `gh repo create name --public` | `curl POST /user/repos` |
| Fork | `gh repo fork o/r --clone` | `curl POST /repos/o/r/forks` + `git clone` |
| Repo info | `gh repo view o/r` | `curl GET /repos/o/r` |
| Edit settings | `gh repo edit --...` | `curl PATCH /repos/o/r` |
| Create release | `gh release create v1.0` | `curl POST /repos/o/r/releases` |
| List workflows | `gh workflow list` | `curl GET /repos/o/r/actions/workflows` |
| Set secret | `gh secret set KEY` | `curl PUT /repos/o/r/actions/secrets/KEY` (+ encryption) |

See `references/github-repo-management.md` for full details including branch protection, Gists, and deployment upgrades.

---

## Section 3: Pull Request Workflow

Complete PR lifecycle: branch, commit, open, CI, merge.

### Branch and Commit

```bash
git checkout main && git pull origin main
git checkout -b feat/add-user-authentication
# ... make changes ...
git add src/auth.py tests/test_auth.py
git commit -m "feat: add JWT-based user authentication"
git push -u origin HEAD
```

### Create PR

**gh:** `gh pr create --title "feat: add JWT auth" --body "## Summary\n..."`
**curl:** POST to `/repos/$OWNER/$REPO/pulls`

### Monitor CI

**gh:** `gh pr checks --watch`
**curl:** GET `/repos/$OWNER/$REPO/commits/$SHA/status`

### Merge

**gh:** `gh pr merge --squash --delete-branch`
**curl:** PUT `/repos/$OWNER/$REPO/pulls/$PR_NUMBER/merge`

See `references/github-pr-workflow.md` for auto-fix loops, polling, and auto-merge setup.

---

## Section 4: Issues Management

Create, search, triage, label, assign, and close issues.

### Quick Reference

| Action | gh | curl endpoint |
|--------|-----|--------------|
| List issues | `gh issue list` | `GET /repos/{o}/{r}/issues` |
| View issue | `gh issue view N` | `GET /repos/{o}/{r}/issues/N` |
| Create issue | `gh issue create ...` | `POST /repos/{o}/{r}/issues` |
| Add labels | `gh issue edit N --add-label ...` | `POST /repos/{o}/{r}/issues/N/labels` |
| Assign | `gh issue edit N --add-assignee ...` | `POST /repos/{o}/{r}/issues/N/assignees` |
| Comment | `gh issue comment N --body ...` | `POST /repos/{o}/{r}/issues/N/comments` |
| Close | `gh issue close N` | `PATCH /repos/{o}/{r}/issues/N` |
| Search | `gh issue list --search "..."` | `GET /search/issues?q=...` |

See `references/github-issues.md` for bug/feature templates and triage workflow.

---

## Section 5: Code Review

Review local changes (pre-push) or open PRs on GitHub.

### Pre-Push Review

```bash
git diff main...HEAD --stat     # scope
git diff main...HEAD            # full diff
read_file on changed files      # full context
```

Check for: debug statements, secrets, large files, merge conflict markers.

### PR Review on GitHub

**gh:** `gh pr view 123` + `gh pr diff 123` + `gh pr review 123 --approve/--request-changes`
**curl:** GET PR details + POST reviews with inline comments

### Review Output Format

```
## Code Review Summary
### Critical
- **src/auth.py:45** — SQL injection vulnerability
### Warnings
- **src/models.py:23** — Plaintext password storage
### Suggestions
- **src/utils.py:8** — Duplicated logic
### Looks Good
- Clean separation of concerns
```

See `references/github-code-review.md` for the full review checklist and inline comment API patterns.

---

## Codebase Inspection

Analyze repositories for LOC, language breakdown, and code-vs-comment ratios using `pygount`.

```bash
pip install pygount
pygount --format=summary \
  --folders-to-skip=".git,node_modules,venv,.venv,__pycache__,.cache,dist,build" .
```

**Pitfalls:** Always use `--folders-to-skip` to exclude dependency dirs. Markdown shows 0 code lines (classified as comments).

**See:** `references/codebase-inspection.md` for full options and output format details.

---

## Troubleshooting

| Problem | Solution |
|---------|----------|
| `git push` asks for password | Use personal access token as password, or switch to SSH |
| `remote: Permission denied` | Token may lack `repo` scope |
| `fatal: Authentication failed` | Cached credentials stale — re-authenticate |
| SSH port 22 blocked | Add `Port 443` + `Hostname ssh.github.com` to `~/.ssh/config` |
| Credentials not persisting | Check `git config --global credential.helper` |