{"canonical_url":"https://engineer.company/glossary/quality-gate/","content_markdown":"# Quality gate\n\n## What it is\n\nA quality gate is a set of conditions a change has to meet before it may move\nto the next stage, with one result at the end: pass or fail. The stage can be a\ncommit, a merge into the main branch, a release or a deployment. The conditions\nare anything a machine can decide: a clean lint run, passing tests, a coverage\nfigure, a build that completes.\n\nThe word doing the work is gate. A check reports; a gate decides, and the\ndecision is enforced by whatever controls the next step. A linter that prints\nforty warnings into a log is a check. The same linter wired so that the merge\nbutton stays disabled until its output is clean is part of a gate.\n\nSonarQube Cloud, where the term is a named feature, describes a quality gate as\na set of conditions against which code is measured during analysis. Each\ncondition pairs a metric with a comparison operator and an error value, so\n\"reliability issues greater than 0\" is a condition, and if any condition is\nmet, the gate fails. A condition applies either to new code or to the code as a\nwhole.\n\nThe hosting platforms build the same idea into their merge flow:\n\n- **GitHub** has a branch protection setting, \"Require status checks before\n  merging\". A required check must report a successful, skipped or neutral\n  status before changes reach the protected branch.\n- **GitLab** has a merge check called \"Pipelines must succeed\". Once it is\n  selected, a merge request cannot merge while its pipeline is failing, and it\n  also cannot merge when there is no pipeline at all.\n- **On a developer's own machine**, pre-commit installs checks as Git hooks\n  that run at commit or at push, and a task runner such as Task gives the whole\n  set one name.\n\n## Why it matters\n\nA standard that lives only in a document gets negotiated one exception at a\ntime. A standard that fails the build is followed by everyone, including the\nperson who wrote it, on the afternoon when they would rather skip it. A gate\nmakes agreed rules executable, so keeping them stops depending on memory and\nmood.\n\nIt also changes what human review is for. When a machine has already caught\nformatting, unused imports, broken links and leaked secrets, the reviewer can\nspend their attention on intent and design, which a machine cannot judge. The\nbar is also the same for every author.\n\nThe new-code idea makes a gate adoptable on an old codebase. Sonar way, the\ndefault gate in SonarQube Cloud, focuses on new code rather than on remediating\nold code, with conditions such as at least 80.0% test coverage and at most\n3.0% duplication in new code. On a pull request, only conditions about new code\nare used. A project with thousands of existing issues can switch the gate on\nand hold every new change to the bar without first paying off the backlog.\n\nSpeed decides whether people keep the gate switched on. Task runs a task's\ndependencies concurrently, so a gate built from many independent checks can\nrun them side by side instead of one after another. Splitting the checks by\ncost helps too: the cheap half on every commit, the full set before code leaves\nthe machine.\n\nThis site has its own gate: `task check`, run on the machine the site is written\non rather than on a hosted build service. Every diagnostic counts as an error,\nthe site generator runs with `--panicOnWarning` so that even a deprecation\nnotice stops the build, and inline suppressions such as `# noqa` or\n`stylelint-disable` are prohibited, so a failure gets fixed at its cause instead\nof silenced. A pre-commit hook runs the file-level checks on every commit, and a\npre-push hook runs the full `task check`, which takes minutes rather than\nseconds. A green run from a clean tree stamps that tree, and the deploy script\nrefuses a tree without a stamp. Its one override is an environment variable that\nprints a loud warning, so whoever skips the gate in an emergency has to say so.\n\n## What it looks like in practice\n\nThe site's [credits page](/credits/) lists the tools inside that gate: vnu\nfor HTML, Stylelint, axe-core across a page per template, Lighthouse, lychee for links,\nPrettier, markdownlint, ESLint, Ruff, basedpyright, yamllint, ShellCheck,\ncodespell and gitleaks. Task runs all of it under one name per job, and\npre-commit runs the file-level half again on every commit. The page also names\nwhat stays outside the gate: two of the browser checks driven by Puppeteer,\nviewport overflow and the visual regression, which a person runs on demand.\n\nA one-person project has no reviewer at all, which is the situation one\nportfolio page starts from. The standards had to be executable, so that\nbreaking one fails the commit instead of waiting for someone to notice. The\nanswer, at the documented August 2026 implementation stage, was\n[a commit gate of 22 linters with no warning tier](/portfolio/built-a-22-linter-commit-gate/),\nplus project-specific checks that no off-the-shelf tool has an opinion on,\nsuch as that the deployed tree holds no private path or hostname and that the\ncopy kept its tone rules in three languages. A failure already present is\nfixed in the same pass rather than accepted. The page names the cost plainly:\ncommitting is slow, and the gate is the only reviewer the project has.\n\nA gate can also disagree with itself. Another page describes a project with a\ncommit hook and a full gate, a document saying the hook ran the gate, and two\nlists of checks kept by hand in two files.\n[A test that resolves both lists to the checks they actually invoke](/portfolio/found-the-hooks-and-the-gate-disagreeing/)\nshowed five checks running only in the full gate, and they were exactly the\nones that read the prose. Every check protecting code ran automatically; every\ncheck protecting the writing ran only when someone remembered. The five moved\ninto the hook, two of them were made fast enough to fit its time budget, and\nthe comparison test stayed to catch differences between the lists.\n\n## Where it goes wrong\n\nMost gates fail by letting things through while still showing green.\n\n**Warnings pile up behind a pass.** A gate that fails only on errors lets\nwarnings accumulate until the log is too long to read, and then a real problem\narrives as warning number two hundred and one. Drop the warning tier: either a\nrule is worth failing on, or it is switched off.\n\n**A skipped check counts as a pass.** On GitHub, a skipped status satisfies a\nrequired check, and a job skipped by its `if:` condition reports success. A job\nthat depends on a failed job is skipped too, and may not block the merge.\nGitHub's advice is to use `always()` with `needs`: require one job that always\nruns and passes only when everything it needs succeeded.\n\n```yaml\n# .github/workflows/check.yml (excerpt)\njobs:\n    gate:\n        if: always()\n        needs: [lint, test, build]\n        runs-on: ubuntu-latest\n        steps:\n            - run: |\n                  for result in ${{ join(needs.*.result, ' ') }}; do\n                      test \"$result\" = success || exit 1\n                  done\n```\n\nThe opposite trap also exists: a required workflow skipped by a path or branch\nfilter leaves its checks pending and blocks every merge. Avoid requiring\nworkflows that can be skipped.\n\n**Two lists drift apart.** The hook runs one set, the server another, and a\ndocument claims they match. Give the checks one definition and call it from\nevery place, or keep a test that compares the lists and fails when they differ.\n\n**The gate gets slow and people go around it.** A flag that skips hooks is\nat hand, and on GitHub branch protection does not apply to repository\nadministrators by default; \"Do not allow bypassing the above settings\" changes\nthat. Measure where the time goes, run independent checks concurrently, keep\nthe commit-time half small, and move a genuinely slow check to a documented\nmanual step.\n\n**A check passes because it checked nothing.** A linter pointed at a glob that\nmatches zero files, or an ignore pattern that swallows a whole directory, exits\ncleanly, and a clean exit looks the same as clean code. Test the gate itself:\ngive each check a file that is known to be wrong and expect it to fail.\n\n## Further reading\n\n- [Introduction to quality gates](https://docs.sonarsource.com/sonarqube-cloud/standards/managing-quality-gates/introduction-to-quality-gates)\n  — conditions, the Sonar way default and the focus on new code.\n- [About protected branches](https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/managing-protected-branches/about-protected-branches)\n  — required status checks and who may bypass them.\n- [Troubleshooting required status checks](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/collaborating-on-repositories-with-code-quality-features/troubleshooting-required-status-checks)\n  — which statuses count as passing, and how skipped workflows and jobs behave.\n- [Auto-merge](https://docs.gitlab.com/user/project/merge_requests/auto_merge/)\n  — GitLab's \"Pipelines must succeed\" check and how it treats skipped\n  pipelines.\n- [pre-commit](https://pre-commit.com/) — checks declared once and installed as\n  Git hooks for the commit and push stages.\n- [Task dependencies](https://taskfile.dev/docs/guide/dependencies) — how Task\n  runs a task's dependencies concurrently and its commands in order.\n\n\u003chttps://engineer.company/glossary/quality-gate/\u003e\n","date_modified":"2026-11-12T05:34:23Z","description":"How a quality gate turns written standards into pass-or-fail conditions at commit, merge or deploy, what a working one looks like, and where gates leak.","formats":{"gemtext":"https://engineer.company/glossary/quality-gate/index.gmi","gopher":"https://engineer.company/glossary/quality-gate/gophermap","html":"https://engineer.company/glossary/quality-gate/","json":"https://engineer.company/glossary/quality-gate/index.json","markdown":"https://engineer.company/glossary/quality-gate/index.md","pdf":"https://engineer.company/glossary/quality-gate/index.pdf"},"kind":"page","language":"en","title":"What is a quality gate?","url":"https://engineer.company/glossary/quality-gate/","version":1}