pr-workflow

name	pr-workflow
description	Guide pull request creation, review process, CI gates, and merge strategies. Use when the user creates a PR, asks about PR templates, review workflows, CODEOWNERS setup, or merge strategies. Apply when running gh pr create.

Pull Request Workflow

Structure PRs for effective code review, automated CI validation, and clean merge history.

When to Use

• Creating a pull request with gh pr create or GitHub UI
• Setting up PR templates for a repository
• Configuring CODEOWNERS for automatic review assignment
• Choosing between squash, merge, and rebase merge strategies
• Reviewing or improving an existing PR workflow

Core Patterns

PR Creation with gh CLI

Always analyze changes before creating a PR:

# 1. Check what will be in the PR
git log main..HEAD --oneline
git diff main...HEAD --stat

# 2. Push branch with upstream tracking
git push -u origin feature/AUTH-123-add-sso

# 3. Create PR with structured body
gh pr create --title "feat(auth): add SSO login via SAML" --body "$(cat <<'EOF'
## Summary
- Add SAML-based SSO authentication flow
- Integrate with identity provider discovery endpoint
- Store SSO sessions with configurable TTL

## Changes
- `src/auth/sso.ts` — SAML assertion parsing and validation
- `src/auth/routes.ts` — New `/auth/sso/callback` endpoint
- `src/config/sso.ts` — SSO provider configuration schema

## Test Plan
- [ ] Unit tests for SAML assertion parsing
- [ ] Integration test with mock IdP
- [ ] Manual test with Okta sandbox
- [ ] Verify session expiration behavior

Closes #142
EOF
)"

PR Template

Create .github/pull_request_template.md in the repository:

## Summary
<!-- 1-3 bullet points describing WHAT changed and WHY -->

## Changes
<!-- List key files changed and what was modified -->

## Test Plan
<!-- How to verify this works correctly -->
- [ ] Unit tests pass
- [ ] Integration tests pass
- [ ] Manual testing steps documented

## Screenshots
<!-- If UI changes, include before/after screenshots -->

## Checklist
- [ ] Tests added/updated
- [ ] Documentation updated (if needed)
- [ ] No breaking changes (or noted in description)
- [ ] Self-reviewed the diff

CODEOWNERS Setup

Create .github/CODEOWNERS to auto-assign reviewers:

# Default owners for everything
* @org/engineering-leads

# Frontend owned by frontend team
src/components/     @org/frontend
src/pages/          @org/frontend
src/styles/         @org/frontend

# API and backend
src/api/            @org/backend
src/services/       @org/backend
src/models/         @org/backend

# Infrastructure
Dockerfile          @org/devops
docker-compose.yml  @org/devops
.github/workflows/  @org/devops
terraform/          @org/devops

# Security-sensitive files require security review
src/auth/           @org/security @org/backend
src/crypto/         @org/security

Merge Strategy Selection

# SQUASH MERGE: Default for feature PRs
# Produces one clean commit on main
gh pr merge 123 --squash

# MERGE COMMIT: For release branches or when history matters
# Preserves all individual commits
gh pr merge 123 --merge

# REBASE MERGE: For clean, linear history
# Replays commits on top of base branch
gh pr merge 123 --rebase

Strategy	Best For	Result
Squash	Feature PRs, messy history	Single commit on main
Merge	Release branches, audit trails	Merge commit + all commits
Rebase	Clean PRs with good commits	Linear history, no merge commit

Draft PRs and Review Process

# Create draft PR for early feedback
gh pr create --draft --title "WIP: refactor auth module"

# Mark ready for review when done
gh pr ready 123

# Request specific reviewers
gh pr create --reviewer "alice,bob" --title "feat: add caching layer"

# Add reviewers to existing PR
gh pr edit 123 --add-reviewer "alice"

# Check CI status before merging
gh pr checks 123

# View review status
gh pr view 123

Review workflow stages:

1. Draft PR — Open early for visibility, not ready for review
2. Ready for Review — All CI passing, self-reviewed, description complete
3. Changes Requested — Address feedback, push new commits (do not force-push)
4. Approved — Merge when CI is green and approvals are met
5. Merged — Delete the source branch

CI Gates Configuration

Example GitHub Actions workflow for PR validation:

# .github/workflows/pr-checks.yml
name: PR Checks
on:
  pull_request:
    branches: [main, develop]

jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
      - run: npm ci
      - run: npm run lint
      - run: npm run typecheck
      - run: npm test -- --coverage
      - run: npm run build

Configure branch protection to require these checks before merging.

Anti-Patterns

What NOT to Do

• Giant PRs: PRs over 400 lines are hard to review and likely to hide bugs. Split into smaller, focused PRs.
• No description: A PR with just a title gives reviewers no context. Always include summary, changes, and test plan.
• Force-pushing during review: Reviewers lose context of what changed between review rounds. Push new commits instead.
• Merging with failing CI: Never override CI checks to merge faster. Fix the failures.
• Self-approving: Even solo developers benefit from CI gates. Do not bypass required reviews.

# BAD: No description
gh pr create --title "updates"

# BAD: Force push during review
git rebase -i HEAD~5
git push --force  # Reviewer comments now point to nonexistent commits

# GOOD: Push fixup commits during review
git commit -m "fix: address review feedback on input validation"
git push

Quick Reference

PR Creation Checklist:
  1. git log main..HEAD — review all commits
  2. git diff main...HEAD --stat — verify changed files
  3. git push -u origin <branch> — push with tracking
  4. gh pr create — with title, body, reviewers

PR Title Format:
  <type>(<scope>): <description>    (matches commit conventions)

PR Body Sections:
  ## Summary         — WHAT and WHY (1-3 bullets)
  ## Changes         — Key files and modifications
  ## Test Plan       — How to verify correctness
  ## Screenshots     — Before/after for UI changes

Merge Strategy:
  Feature PRs        -> squash merge
  Release branches   -> merge commit
  Clean linear PRs   -> rebase merge

Files to Set Up:
  .github/pull_request_template.md  — PR template
  .github/CODEOWNERS                — Auto-assign reviewers
  .github/workflows/pr-checks.yml  — CI gates

Commands:
  gh pr create --draft              — Early visibility
  gh pr ready 123                   — Mark ready for review
  gh pr checks 123                  — Verify CI status
  gh pr merge 123 --squash          — Squash merge