By admin , 29 April 2026

What you will achieve

You will configure a code review workflow that scales from three to thirty contributors: branch protection, CODEOWNERS, PR templates, automated checks, and conventions for reviewers and authors. By the end, the repo enforces a process that catches bugs early and onboards new contributors smoothly.

Step 1: choose a model

The dominant model in 2026 is GitHub Flow:

  • Single long-lived main branch.
  • Feature branches off main.
  • PR for review and CI.
  • Merge after approval and green checks.

Variants exist (Git Flow, trunk-based with stacked PRs); pick one and document it.

Step 2: branch protection

On the host's branch protection settings for main:

  • Require a pull request before merging.
  • Require at least one approving review.
  • Dismiss stale approvals on new commits.
  • Require status checks to pass.
  • Require linear history (or squash merges only).
  • Disallow force pushes.
  • Disallow direct deletion.
gh api -X PUT repos/owner/repo/branches/main/protection \
  -F required_pull_request_reviews.required_approving_review_count=1 \
  -F required_status_checks.strict=true \
  -F enforce_admins=true

Step 3: CODEOWNERS

# .github/CODEOWNERS
*               @org/maintainers
/infra/         @org/devops
/docs/          @org/docs-team
*.sql           @org/dba

Now PRs touching specific paths automatically request review from the right teams.

Step 4: PR template

# .github/PULL_REQUEST_TEMPLATE.md
## Summary
Brief description of the change.

## Why
Context, links to issues.

## How tested
- [ ] Unit tests added/updated
- [ ] Manual smoke test
- [ ] CI green

## Screenshots / videos (UI only)

## Risk and rollback
Anything reviewers should worry about.

Step 5: automated checks

CI workflow gates merging:

# .github/workflows/ci.yml
name: CI
on:
  pull_request:
  push:
    branches: [main]
jobs:
  test:
    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

Step 6: bot integrations

  • Dependabot / Renovate - automated dependency PRs.
  • gitleaks action - secret scanning per PR.
  • Codecov or Coveralls - coverage reporting.
  • danger.js or danger-rb - custom PR checks (PR description present, breaking-change tags, etc.).

Step 7: review conventions

Document author and reviewer expectations:

# CONTRIBUTING.md
## For authors
- Branch off main; name `type/PROJ-1234-description`.
- Keep PRs under 400 lines if possible.
- Self-review the diff before requesting review.
- Link the ticket; include screenshots for UI changes.
- Address every reviewer comment - either by fix or reply.

## For reviewers
- Respond within one working day.
- Distinguish blocking comments from suggestions.
- Approve or request changes; do not leave PRs in limbo.
- Trust the author's judgement on style; flag correctness, security, and design.

Step 8: comment conventions

Adopt a clear set of comment prefixes:

  • nit: minor stylistic suggestion, non-blocking.
  • question: seeking clarification, not blocking.
  • suggestion: proposed change, author can accept or decline.
  • blocker: must be addressed before merge.
  • praise: calling out something well done.

Step 9: review small, review often

  • PRs over 400 lines get less thorough review (research-backed).
  • Encourage stacked PRs for large features - small reviews chained together.
  • Authors should self-review before requesting; the first reviewer should not be debugging typos.

Step 10: handling disagreements

Reviewer and author disagree:

  1. Discuss in PR comments.
  2. If unresolved, escalate to a third reviewer or tech lead.
  3. If still unresolved, decide via team discussion offline; document the outcome.

Step 11: post-merge hygiene

  • Auto-delete merged branches (host setting).
  • Run a periodic "open PR sweep" - close stale PRs.
  • Track PR cycle time as a team health metric.

Step 12: continuous improvement

Hold a quarterly retro on the review process. What is taking too long? What checks are noisy? What is being caught only in production? Iterate.

The result

The repo's review workflow is documented, automated where possible, and respectful of contributors' time. New hires can read CONTRIBUTING.md and ship a PR on day two. The process catches bugs and grows engineering judgement; the team trusts the system to keep main healthy.