diff --git a/skills/devops/github/SKILL.md b/skills/devops/github/SKILL.md new file mode 100644 index 0000000..50609d2 --- /dev/null +++ b/skills/devops/github/SKILL.md @@ -0,0 +1,199 @@ +--- +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//.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` |