github-pr-workflow

GitHub Pull Request Workflow

Complete guide for managing the PR lifecycle with the gh CLI. On a machine without gh, see references/rest-api-fallback.md.

Prerequisites

• Authenticated with GitHub (see github-auth skill — ask to install gh if it's missing, that's the default path)
• Inside a git repository with a GitHub remote
• gh genuinely can't be installed: references/rest-api-fallback.md (auth detection, token setup, REST calls)

1. Branch Creation

This part is pure git — identical either way:

# Make sure you're up to date
git fetch origin
git checkout main && git pull origin main

# Create and switch to a new branch
git checkout -b feat/add-user-authentication

Branch naming conventions:

• feat/description — new features
• fix/description — bug fixes
• refactor/description — code restructuring
• docs/description — documentation
• ci/description — CI/CD changes

2. Making Commits

Use the agent's file tools (write_file, patch) to make changes, then commit:

# Stage specific files
git add src/auth.py src/models/user.py tests/test_auth.py

# Commit with a conventional commit message
git commit -m "feat: add JWT-based user authentication

- Add login/register endpoints
- Add User model with password hashing
- Add auth middleware for protected routes
- Add unit tests for auth flow"

Commit message format (Conventional Commits):

type(scope): short description

Longer explanation if needed. Wrap at 72 characters.

Types: feat, fix, refactor, docs, test, ci, chore, perf

Mandatory pre-push checklist: see the repo-conventions skill (line endings: see the git-line-endings skill).

3. Pushing and Creating a PR

No gh? Install it (see github-auth) — genuine fallback: references/rest-api-fallback.md.

Push the Branch (same either way)

git push -u origin HEAD

Create the PR

With gh:

gh pr create \
  --title "feat: add JWT-based user authentication" \
  --body "## Summary
- Adds login and register API endpoints
- JWT token generation and validation

## Test Plan
- [ ] Unit tests pass

Closes #42"