---
name: github
description: Complete GitHub workflow — auth setup, repo management, PR lifecycle, code review, and issue triage via gh CLI or git+curl fallback.
version: 1.0.0
author: Hermes Agent
license: MIT
metadata:
  hermes:
    tags: [GitHub, Authentication, Code-Review, Pull-Requests, Issues, Repositories, CI/CD, Git]
    related_skills: []
---

# GitHub — Complete Workflow Guide

Single reference for all GitHub operations: authentication, repository management, PR lifecycle, code review, and issue triage. Every section shows the `gh` CLI way first, then the `git` + `curl` fallback.

## Quick Auth Detection

```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

# Extract owner/repo from git remote
REMOTE_URL=$(git remote get-url origin 2>/dev/null || echo "")
if [ -n "$REMOTE_URL" ]; then
  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)
fi
```

Script reference: `scripts/gh-env.sh` (sourced in workflows that need persistent env).

---

## Section A — Authentication Setup

Two reliable paths:

### A1. Git-Only (HTTPS + Personal Access Token)

```bash
# Configure credential helper
git config --global credential.helper store
git config --global user.name "Your Name"
git config --global user.email "your@email.com"

# Use the token as password when prompted
git ls-remote https://github.com/<username>/<repo>.git
```

**Alternative — cache helper** (credentials expire from memory):
```bash
git config --global credential.helper 'cache --timeout=28800'
```

### A2. SSH Key Auth

```bash
ssh-keygen -t ed25519 -C "your@email.com" -f ~/.ssh/id_ed25519 -N ""
cat ~/.ssh/id_ed25519.pub  # Add to https://github.com/settings/keys
ssh -T git@github.com
git config --global url."git@github.com:".insteadOf "https://github.com/"
```

### A3. gh CLI Auth

```bash
# Interactive browser login
gh auth login

# Token-based (headless)
echo "<token>" | gh auth login --with-token
gh auth setup-git
```

### A4. API Access Without gh

```bash
export GITHUB_TOKEN="<token>"
curl -s -H "Authorization: token $GITHUB_TOKEN" https://api.github.com/user
```

See `references/github-api-cheatsheet.md` for common API endpoint patterns.

---

## Section B — Repository Management

### Cloning

```bash
git clone https://github.com/owner/repo.git
gh repo clone owner/repo
```

### Creating Repos

```bash
# gh
gh repo create my-project --public --clone

# curl
curl -s -X POST -H "Authorization: token $GITHUB_TOKEN" \
  https://api.github.com/user/repos \
  -d '{"name": "my-project", "private": false}'
```

### Forking & Sync

```bash
gh repo fork owner/repo --clone

# Keep fork in sync
git fetch upstream && git merge upstream/main && git push
gh repo sync <user>/<repo>
```

### Releases

```bash
gh release create v1.0.0 --title "v1.0.0" --generate-notes

# curl
curl -X POST -H "Authorization: token $GITHUB_TOKEN" \
  https://api.github.com/repos/$OWNER/$REPO/releases \
  -d '{"tag_name": "v1.0.0", "name": "v1.0.0"}'
```

### Secrets (GitHub Actions)

```bash
gh secret set API_KEY --body "value"

# curl requires encryption with the repo's public key (much more complex)
# Prefer gh for secrets.
```

---

## Section C — Pull Request Lifecycle

### Branch + Commit

```bash
git checkout -b feat/description
git add <files>
git commit -m "feat: add feature description"
git push -u origin HEAD
```

### Create PR

```bash
# gh
gh pr create --title "feat: ..." --body "## Summary..." --label enhancement

# curl
curl -s -X POST -H "Authorization: token $GITHUB_TOKEN" \
  https://api.github.com/repos/$OWNER/$REPO/pulls \
  -d '{"title": "feat: ...", "head": "'$(git branch --show-current)'", "base": "main"}'
```

### CI Monitoring

```bash
gh pr checks --watch

git log --oneline --format="%H %s" | head -1 | xargs -I{} \
  curl -s -H "Authorization: token $GITHUB_TOKEN" \
  https://api.github.com/repos/$OWNER/$REPO/commits/{}/status
```

### Merging

```bash
gh pr merge --squash --delete-branch

curl -X PUT -H "Authorization: token $GITHUB_TOKEN" \
  https://api.github.com/repos/$OWNER/$REPO/pulls/$N/merge \
  -d '{"merge_method": "squash"}'
```

See `references/conventional-commits.md` for commit message format.

---

## Section D — Code Review

### Local Changes Review (Pre-Push)

```bash
git diff main...HEAD --stat     # scope of changes
git diff main...HEAD            # full diff
git diff main...HEAD -- src/   # file-specific

# Check for common issues
git diff main...HEAD | grep -n "TODO\|FIXME\|debugger\|console\.log"
git diff main...HEAD | grep -in "password\|secret\|api_key"
git diff main...HEAD --stat | sort -t'|' -k2 -rn | head -10
```

### PR Review

```bash
gh pr view $N && gh pr diff $N
git fetch origin pull/$N/head:pr-$N && git checkout pr-$N
gh pr review $N --approve --body "LGTM"
gh pr review $N --request-changes --body "See comments"
```

### Inline Comments (curl)

```bash
HEAD_SHA=$(curl -s -H "Authorization: token $GITHUB_TOKEN" \
  https://api.github.com/repos/$OWNER/$REPO/pulls/$N \
  | python3 -c "import sys,json; print(json.load(sys.stdin)['head']['sha'])")

curl -s -X POST -H "Authorization: token $GITHUB_TOKEN" \
  https://api.github.com/repos/$OWNER/$REPO/pulls/$N/reviews \
  -d '{
    "commit_id": "'$HEAD_SHA'",
    "event": "COMMENT",
    "body": "Code review from Hermes Agent",
    "comments": [
      {"path": "src/auth.py", "line": 45, "body": "Use parameterized queries."}
    ]
  }'
```

See `references/review-output-template.md` for the structured review format.

---

## Section E — Issues Management

### Viewing

```bash
gh issue list
gh issue list --label bug --state open
gh issue view $N

curl -s -H "Authorization: token $GITHUB_TOKEN" \
  "https://api.github.com/repos/$OWNER/$REPO/issues?state=open"
```

### Creating

```bash
gh issue create --title "Bug" --body "Steps..." --label bug

curl -X POST -H "Authorization: token $GITHUB_TOKEN" \
  https://api.github.com/repos/$OWNER/$REPO/issues \
  -d '{"title": "Bug", "body": "Steps...", "labels": ["bug"]}'
```

### Managing (Labels, Assign, Close)

```bash
gh issue edit $N --add-label "priority:high"
gh issue edit $N --add-assignee username
gh issue close $N
gh issue comment $N --body "Fixed in PR #99"

curl -X PATCH -H "Authorization: token $GITHUB_TOKEN" \
  https://api.github.com/repos/$OWNER/$REPO/issues/$N \
  -d '{"state": "closed"}'
```

See `templates/bug-report.md` and `templates/feature-request.md` for issue body templates.

---

## Section F — CI/CD & Actions

```bash
gh workflow list
gh run list --limit 10
gh run view <ID> --log-failed
gh run rerun <ID> --failed
gh workflow run deploy.yml -f environment=staging

# curl
curl -s -H "Authorization: token $GITHUB_TOKEN" \
  https://api.github.com/repos/$OWNER/$REPO/actions/workflows
```

See `references/ci-troubleshooting.md` for common CI failure patterns and fixes.

---

## Pitfalls

1. **Username vs numeric ID** — Not relevant for GitHub (unlike Telegram), but tokens expire. Set appropriate expiration (90 days default).
2. **`gh` not available** — Every operation has a `git` + `curl` fallback. Prefer it for CI/automation where `gh` may not be installed.
3. **Token in config.yaml** — Never put secrets in config.yaml. Use `.env` tokens only.
4. **Branch protection** — `gh pr merge` will fail on protected branches without approval. Use `gh pr merge --auto` for auto-merge when checks pass.
5. **Large repos** — Use `--depth 1` shallow clones to save time and disk.
6. **Conflicting workflow names** — GitHub Actions workflow filenames must be unique within a repo.
7. **Secrets via curl** — Requires encryption with the repo's public key. Always prefer `gh secret set`.
8. **Rate limits** — Unauthenticated API calls are limited to 60/hour. Authenticated: 5000/hour.

## Verification Checklist

- [ ] Auth method detected (gh or curl) before operations
- [ ] `GITHUB_TOKEN` or `gh auth status` confirmed functional
- [ ] git identity configured (`user.name` + `user.email`)
- [ ] PR body references issues with `Closes #N` for auto-close
- [ ] CI checks monitored and passing before merge
- [ ] Stale review branches cleaned up after merge

## Support Files

| File | Purpose |
|------|---------|
| `scripts/gh-env.sh` | Persistent auth detection script (source in workflows) |
| `references/review-output-template.md` | Structured code review output format |
| `references/ci-troubleshooting.md` | Common CI failure patterns and fixes |
| `references/conventional-commits.md` | Commit message format guide |
| `references/github-api-cheatsheet.md` | Common REST API endpoint reference |
| `templates/bug-report.md` | Bug report issue body template |
| `templates/feature-request.md` | Feature request issue body template |
| `templates/pr-body-feature.md` | Feature PR body template |
| `templates/pr-body-bugfix.md` | Bugfix PR body template |
