Skip to content
Tutorials Center
My learning

Topics

Lesson 26 of 44 ยท Testing and Quality Gates

Linting, Coverage and Quality Gates

Add linters, formatters, coverage thresholds, required status checks, branch protection and CODEOWNERS to turn CI results into rules that block bad merges.

A pipeline that only reports problems is advice. A pipeline that stops a bad change from merging is a rule. The difference is a quality gate: a check with a clear pass/fail verdict that the repository refuses to merge without.

In this lesson you will look at the checks that are worth gating on (linters, formatters, type checkers, coverage), the repository settings that make the gate binding (required status checks, branch protection, CODEOWNERS), and how pre-commit hooks and CI complement each other. If you need the basics of a workflow file, start with Your First Workflow.

GitHub, GitLab and Jenkins cannot run on this site, so workflow files and settings are shown read-only. The TryIt blocks are stand-ins: a Python coverage calculator and a JavaScript CODEOWNERS matcher, so you can see the logic that the real tools apply.

What to check automatically

Good gates are fast, deterministic and owned. Typical ones:

  • Formatter check. A formatter (Prettier, Black, gofmt, cargo fmt) rewrites code into one style. In CI you run it in check mode (for example prettier --check . or black --check .), which fails if any file would change. This ends style debates in review.
  • Linter. A linter (ESLint, Ruff, golangci-lint, Checkstyle, PHPStan) finds likely bugs and rule violations. Start with the rules your team already agrees on and treat warnings as errors in CI so they do not pile up.
  • Type check. tsc --noEmit, mypy or pyright catch a whole class of bugs before any test runs.
  • Tests and coverage. Tests prove behavior; coverage tells you how much code the tests ran.
  • Security checks. Dependency review and secret scanning, covered in Securing Your Pipeline.

A read-only workflow with a fast lint job and a test job that produces coverage:

YAML
name: quality
on:
  pull_request:

jobs:
  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 22
          cache: npm
      - run: npm ci
      - run: npx prettier --check .
      - run: npx eslint . --max-warnings 0
      - run: npx tsc --noEmit

  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 22
          cache: npm
      - run: npm ci
      - run: npx vitest run --coverage
      - uses: actions/upload-artifact@v4
        if: ${{ !cancelled() }}
        with:
          name: coverage
          path: coverage/

--max-warnings 0 is the important flag on the ESLint line: with it, any warning fails the job, so warnings cannot silently accumulate.

Coverage: useful, but easy to misuse

Line coverage is the percentage of executable lines that ran during tests. Branch coverage counts each side of an if separately. A coverage number says what was executed, not what was verified: a test that calls a function and asserts nothing still raises coverage. So use coverage as a floor and a trend, not as a goal in itself.

Three common gate styles:

  1. Absolute threshold. "Total coverage must be at least 80%."
  2. Ratchet. "Coverage may not drop more than 1 point compared with main." Good for legacy projects, because it prevents decay without demanding a big-bang cleanup.
  3. Diff (patch) coverage. "Lines changed in this pull request must be at least 90% covered." This is the fairest rule, because new code is held to a high bar without punishing old gaps.

The Python program below computes all three from raw hit data and prints a verdict. The real tools (coverage.py, Istanbul/c8, JaCoCo, Codecov, SonarQube) do the same arithmetic on much bigger data.

Python Coverage percentage and gate verdict

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Try changing the hit counts for line 4 and 5 of cart.py to 3 and see which gates turn green. You will notice that a project can fail the absolute rule while passing the ratchet: that is exactly why legacy teams like ratchets.

Coverage uploaded as a number is not a gate on its own. Something must read it and set a job status. Many projects set coverageThreshold in the test runner config (so the test command itself exits non-zero), or use a service whose status check is required.

Required status checks and branch protection

A check that fails but can be merged anyway is only decoration. The enforcement lives in repository settings:

  • Branch protection rules (or newer rulesets) apply to branches such as main.
  • Require status checks to pass before merging lists the jobs by name (for example lint and test). The names come from the job's name: or its ID, so renaming a job quietly removes it from the requirement unless you update the list.
  • Require branches to be up to date forces a rebase or merge with the base branch, so the checks ran against what will really be on main.
  • Require pull request reviews and Require review from Code Owners make a human sign off.
  • Do not allow bypassing applies the rules to admins too.
flowchart LR
    PR["Pull request"] --> C1["lint: pass"]
    PR --> C2["test: pass"]
    PR --> R["Owner review: approved"]
    C1 --> G{"All required<br/>checks green?"}
    C2 --> G
    R --> G
    G -->|yes| M["Merge allowed"]
    G -->|no| B["Merge blocked"]

Required checks and reviews form a gate: one red check or a missing approval blocks the merge button.

A subtle trap: if a workflow is skipped because of a paths: filter, the required check never reports, and the pull request waits forever with "Expected, waiting for status". Fix this by running the job always and deciding inside it whether there is work to do, or by adding a small always-run job that reports success.

In GitLab the equivalents are protected branches, "Pipelines must succeed" in merge request settings and approval rules. In Jenkins the gate is usually the multibranch pipeline's status reported back to the SCM, and the SCM enforces the rule.

CODEOWNERS

A CODEOWNERS file maps paths to people or teams who must review changes there. On GitHub it lives in .github/CODEOWNERS, in the repository root or in docs/. When "Require review from Code Owners" is enabled, a pull request touching an owned path needs an approval from an owner.

TEXT
# Default owner for everything
*                     @acme/platform

# Frontend
*.tsx                 @acme/web
/src/payments/        @acme/payments @alice
/docs/                @acme/docs

# CI itself needs extra care
/.github/workflows/   @acme/security

The rule that surprises people: the last matching pattern wins, and it replaces earlier matches rather than adding to them. Note how CI workflows get their own owner. A workflow file can read secrets, so changes to it deserve a second pair of eyes.

JS Who must review this pull request?

Press Run (or Ctrl + Enter) to see the console output here.

No output.

The matcher is a simplified version of the real glob rules (real CODEOWNERS also supports ** patterns), but it shows the key behavior: src/ui/Button.tsx is owned by @acme/web, not by @acme/platform, because the later *.tsx line replaced the default.

Pre-commit hooks versus CI

A pre-commit hook runs checks on your machine before a commit is created (tools: the pre-commit framework, Husky, lefthook). It is great for instant feedback: format this file, block a commit that contains a private key. But hooks are optional. They can be skipped with git commit --no-verify, they may not be installed on a new clone, and they run on whatever versions the developer has.

CI is the opposite: slower, but authoritative, because nobody can skip it. So use both:

Pre-commit hook CI
Speed of feedback seconds minutes
Can be bypassed yes no (with required checks)
Environment the developer's machine clean and pinned
Good for formatting, quick lint, secret check everything that must be true

Run the same commands in both places (put them in npm run lint or a Makefile target) so a hook failure and a CI failure mean the same thing.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. A job fails on a pull request but the merge button still works. What is most likely missing?

    A check only blocks merging if branch protection (or a ruleset) lists it as required.
  2. 2. What does patch (diff) coverage measure?

    Patch coverage looks only at changed lines, so new code is held to a high bar without punishing old gaps.
  3. 3. A CODEOWNERS file has * @acme/platform followed later by *.tsx @acme/web. Who owns Button.tsx?

    The last matching pattern wins and replaces earlier matches, so only @acme/web is requested.
  4. 4. Why keep CI checks even when developers run pre-commit hooks?

    Hooks are a convenience on the developer's machine. CI in a clean environment is the authoritative gate.
  5. 5. Why use eslint --max-warnings 0 in CI?

    Without it, a linter exits successfully with warnings, and the warnings grow until nobody reads them.

Summary

  • A quality gate is a fast, deterministic check whose result can block a merge.
  • Run formatters in check mode, linters with warnings as errors, and type checkers on every pull request.
  • Coverage shows what ran, not what was verified: prefer patch coverage or a ratchet to a single magic number.
  • Required status checks, branch protection and CODEOWNERS are what make the gate binding; job renames and paths: filters can silently break them.
  • Pre-commit hooks give instant feedback, CI gives the final word. Run the same commands in both.

Now harden the pipeline itself in Securing Your Pipeline.