GitHub — Complete Workflow

Everything you need for GitHub from the terminal: authentication, repository management, pull request lifecycle, code review, and issue triage. Uses the gh CLI and GitHub REST API.

When to Use

Load this skill for any GitHub task — a single PR usually touches auth, repo management, PR workflow, and code review. The umbrella covers all five sub-workflows in one place; each is also available as a detailed reference.

Quick Reference: Which Section Do I Need?

1. Authentication

HTTPS Token Auth

# Set up personal access token
gh auth login --hostname github.com --web
# Or: export GITHUB_TOKEN="ghp_..."
gh auth status

SSH Key Auth

ssh-keygen -t ed25519 -C "email@example.com" -f ~/.ssh/github_key
cat ~/.ssh/github_key.pub  # → add to https://github.com/settings/keys
ssh -T git@github.com  # verify
gh auth login --hostname github.com --git-protocol ssh

Token Scopes

Pitfalls

• gh uses HTTPS by default even with SSH key loaded — pass --git-protocol ssh to override
• Token may need SSO authorization for org repos: https://github.com/settings/tokens → Configure SSO
• GITHUB_TOKEN env var takes priority over gh auth — clear it if switching accounts

Full details: references/github-auth.md

2. Repository Management

Clone / Create / Fork

gh repo clone owner/repo              # clone (auto-detects protocol)
gh repo create my-project --private   # create new repo
gh repo fork owner/repo --clone       # fork + clone

Remote Management

git remote add upstream https://github.com/original/repo.git
git remote -v
git fetch upstream
git pull upstream main

Releases

gh release create v1.0.0 --title "v1.0.0" --notes "Release notes"
gh release list

Pitfalls

• Fork syncing: git fetch upstream && git checkout main && git merge upstream/main && git push origin main
• Large repos: use --depth 1 for shallow clone
• gh repo delete requires confirmation — no undo

Full details: references/github-repo-management.md

3. PR Workflow — Full Lifecycle

Create a PR

git checkout -b feature/my-change
# ... make changes ...
git add -A && git commit -m "feat: description"
git push -u origin feature/my-change
gh pr create --title "Title" --body "Description" --base main

PR Body Template

## What
Brief description of the change.

## Why
Context — issue link, design doc, user report.

## How
Technical approach. Key decisions.

## Testing
- [ ] Unit tests pass
- [ ] Manual testing done
- [ ] CI green

## Screenshots (if UI)

CI and Merge

gh pr checks                # check CI status
gh pr merge --squash        # squash-merge
gh pr merge --rebase        # rebase-merge
gh pr close                 # close without merging

Draft PRs

gh pr create --draft --title "WIP: ..."
gh pr ready                  # mark as ready for review

Pitfalls

• Push BEFORE gh pr create — the branch must exist on remote
• Draft PRs can’t be merged until marked ready
• Never force-push after reviewers have started reviewing (destroys their context)
• Merge conflicts: git fetch origin && git merge origin/main first, then fix

Full details: references/github-pr-workflow.md

4. Code Review

Check Out and Review

gh pr checkout 123           # check out PR locally
gh pr diff 123               # view diff
gh pr view 123 --comments    # view existing comments

Posting Review Comments

# Inline comment on a specific file/line
gh api repos/:owner/:repo/pulls/123/comments \
  -f body="This should use `const` instead of `let`" \
  -f commit_id="$(gh pr view 123 --json headRefOid -q .headRefOid)" \
  -f path="src/file.ts" \
  -f line=42

# Approve
gh pr review 123 --approve

# Request changes
gh pr review 123 --request-changes --body "See inline comments"

Review Checklist

• CI passing? (gh pr checks)
• Merge conflicts? (gh pr view 123 --json mergeable)
• Tests cover the change?
• Security-sensitive changes reviewed carefully?
• Changelog / docs updated?

Pitfalls

• Use commit_id from headRefOid, NOT merge commit or base
• Approving re-requests a stale approval notification — check before re-approving
• Large diffs: review by commit (gh pr view 123 --commits) rather than file-by-file

Full details: references/github-code-review.md

5. Issues

Create and Manage

gh issue create --title "Bug: ..." --body "..." --label "bug" --assignee "@me"
gh issue list --label "bug" --state open
gh issue view 42
gh issue close 42 --comment "Fixed in #123"

Labels and Milestones

gh label create "priority:high" --color "d73a4a"
gh issue edit 42 --add-label "priority:high" --milestone "v2.0"

Cross-Referencing

• Fixes #42 in a PR description auto-closes the issue on merge
• gh issue develop 42 creates a branch linked to the issue

Pitfalls

• Labels are case-sensitive: bug ≠ Bug
• Milestones must exist before assigning
• Bulk operations: use gh issue list --json number -q '.[].number' | xargs -I{} gh issue close {}

Full details: references/github-issues.md

Common Cross-Cutting Patterns

PR + Issue Linking

gh issue create --title "Fix login timeout" --body "Users report 30s timeout..."
gh issue develop 42 --name fix/login-timeout --base main
# ... implement ...
gh pr create --title "Fix login timeout (#42)" --body "Closes #42"
gh pr merge --squash
# Issue #42 auto-closes

Full PR Lifecycle (one-liner summary)

Auth → Clone/Fork → Branch → Code → Commit → Push → PR → CI → Review → Merge → Cleanup

References

• references/github-auth.md — Full authentication guide (device flow, SSH, HTTPS, troubleshooting)
• references/github-repo-management.md — Complete repo management
• references/github-pr-workflow.md — Full PR lifecycle documentation
• references/github-code-review.md — In-depth code review guide
• references/github-issues.md — Complete issue management
• references/codebase-inspection.md — Pygount LOC analysis guide (absorbed from former codebase-inspection skill)
• references/device-flow-python.md — Python polling script for GitHub device flow auth
• references/review-output-template.md — Structured code review output format
• references/ci-troubleshooting.md — CI/CD debugging for PRs
• references/conventional-commits.md — Commit message conventions
• references/github-api-cheatsheet.md — REST API 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 bugfixes
• templates/pr-body-feature.md — PR body template for features

Scripts

• scripts/gh-env.sh — Detect auth method and set up environment for GitHub operations

6. Codebase Inspection (merged)

Analyze codebase size with pygount. Triggered by: “how big is this repo”, “LOC analysis”, “inspect codebase”.

pip install pygount
pygount --format=summary .

For multi-language breakdowns use --format=cloc-xml or --format=json. See references/codebase-inspection.md for full usage.

Absorbed: GitHub Ops (Zero-Token CLI)

references/github-ops-cli.md — GitHub operations via gh CLI optimized for zero-token usage: PR review patterns, issue triage, repo management, CI/CD status, releases. Previously a standalone skill (github-ops). Use this reference for optimized CLI command patterns that minimize LLM token consumption.