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