200 lines
6.3 KiB
Markdown
200 lines
6.3 KiB
Markdown
---
|
|
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` |
|