{"canonical_url":"https://engineer.company/glossary/ci/","content_markdown":"# CI\n\n## What it is\n\nCI is short for continuous integration: a way of working in which everyone on a\nteam lands their changes on one shared line of code many times a week, and a\nmachine builds and tests the result each time so that a mistake surfaces while\nits author still remembers making it. The full name, continuous integration, is\nused as often as the abbreviation.\n\nThe word is used for two different things, and keeping them apart saves a lot\nof confusion. The first is the practice, which is about people. Martin Fowler's\narticle on the subject, the source most teams end up quoting, describes it as a\nset of habits: keep one mainline, automate the build, make the build test\nitself, push to the mainline at least daily, build every push, fix a broken\nbuild at once, keep the build fast, hide unfinished work rather than keeping it\non a branch, and let everyone see the state of the build. The article traces\nthe name to Extreme Programming, and notes that Grady Booch used the phrase\nbefore that.\n\nThe second meaning is the machine. When someone says \"the CI is red\", they mean\nthe service that ran the build and reported a failure. GitHub Actions, GitLab\nCI/CD and their peers all share one shape. A file in the repository describes\nthe work: `.github/workflows/*.yml` on GitHub, `.gitlab-ci.yml` at the root on\nGitLab. An event starts it, such as a push, a pull or merge request, a schedule or a\nperson pressing a button. A runner, which is a machine set aside for the\npurpose, checks out the commit, runs the commands in that file, and reports a\npass or a fail back against the commit.\n\nA server on its own is not continuous integration. A team that keeps work on\nbranches for a month and has a server build each branch has automated its\nbuilds, which is useful, but the integrating still happens all at once at the\nend. The practice is the frequent merging; the machine is what makes frequent\nmerging safe enough to keep doing.\n\nContinuous delivery and continuous deployment are the steps that come after.\nDelivery keeps every green build ready to release, and deployment releases each\none automatically. Both depend on CI being in place first, which is why the\nthree are so often written together as CI/CD.\n\n## Why it matters\n\nThe cost of merging two lines of work grows faster than the time they spend\napart. Two people who each changed the same module yesterday can sort out the\nconflict in a few minutes, because both remember what they meant. Two people\nwho diverged six weeks ago are reconstructing intent from diffs. Merging small\npieces often keeps every conflict small, and that is most of the benefit before\nany machine is involved.\n\nThe build on every push adds a second thing: a clean machine that agrees. \"It\nworks on my laptop\" is a claim about one laptop, with its own installed\nlibraries and leftover files. A runner that starts from a fresh checkout every\ntime either reproduces the result or shows where the laptop was special.\n\nSpeed is where the value lives. Fowler's article sets a target of about ten\nminutes for the main build, and the reasoning holds up in practice. A failure\nreported ten minutes after a push goes back to the person who caused it while\nthe change is still on their screen. A failure reported the next morning goes\nto whoever happens to look, and costs an hour of archaeology first.\n\nVisibility matters as well. When the state of the mainline is shown to\neveryone, nobody starts new work on top of a broken build without knowing it,\nand fixing that build becomes the team's first job rather than someone else's\nproblem.\n\nCI also need not mean a hosted service. pre-commit runs a project's checks as\nGit hooks before each commit or push, and its documentation shows the same set\nrun on a server with `pre-commit run --all-files`. Task gives each check a name\nin one `Taskfile.yml`, so a person and a runner call the same command. The\nchecks behind this site follow that model. They run locally, where the pages\nare written, and a full check runs before every push with no hosted build\nservice in between.\n\n## What it looks like in practice\n\nRoughly 4,000 hours were given back once a team stopped releasing by hand.\nGetting software out had relied on manual steps that each person did slightly\ndifferently, until\n[automated build, test and deployment replaced them](/portfolio/streamlined-ci-cd-processes-saving-4000-hours/).\nThe path from a change to production became a standard one rather than an\nimprovised one, and the releases became both faster and more reliable.\n\nOn a project with a long-lived database, the schema is described twice: once by\nthe initial setup and once by 1,022 migrations, numbered 036 through 1102.\n[A CI job builds the database both ways on every change](/portfolio/1022-migrations-behind-a-schema-drift-gate/),\nonce from the fresh schema and once with every migration replayed in order, and\ncompares the structure and the seeded data. Where the two builds differ, the\njob goes red and prints what differs, so a fresh environment and a long-lived\none are the same database by check rather than by assumption.\n\nCI can also keep two halves of one application in agreement. On another\nproject, the API description and the frontend's client are generated in a chain\nthat starts at the database, and the client alone is 44,076 lines of typed\nTypeScript.\n[A CI check holds what the frontend sends against what the API expects](/portfolio/generated-the-api-contract-from-the-database-out/)\nand fails the build when they diverge. That is the result CI exists for: a\nfield that changes on one side only fails in a build, minutes after the change,\ninstead of reaching a user as an error in the browser.\n\n## Where it goes wrong\n\nMost CI setups decay rather than break. Each of these starts small and ends with\na build the team has learned to work around.\n\n**The build takes longer than the work.** Once a push takes forty minutes to\ncome back, people stop waiting for it, batch several changes into one push and\npush less often, which is the opposite of the practice. Measure where the time\ngoes before adding hardware. Cache dependencies, run the fast checks first, and\nmove the slow suites to a second stage or a schedule, so that the main build\nstays near the ten-minute mark.\n\n**The mainline stays red for a day.** A broken build that nobody fixes becomes\nthe normal state, and a second failure arrives unnoticed behind the first. The\nrule that keeps this from happening is plain: whoever broke it fixes it now, or\nreverts the change and fixes it on their own time. A green mainline is the\nthing everyone else is building on.\n\n**Branches live for weeks while the server builds each one.** Every branch\nshows green, and the trouble arrives on the day they merge, all at once. This\nis automated building without the integration. Merge to the mainline at least\ndaily, and keep unfinished features switched off rather than kept apart.\n\n**The server checks one list and the laptop checks another.** Two lists of\ncommands kept by hand drift apart, and then a change passes locally and fails on\nthe server, or the reverse, and nobody trusts either. Give the checks one entry\npoint and call it from both places. With pre-commit, the server can run exactly\nthe hooks every developer runs:\n\n```yaml\n# .gitlab-ci.yml\ncheck:\n    image: python:3.13\n    script:\n        - pip install pre-commit\n        - pre-commit run --all-files --show-diff-on-failure\n```\n\n**A flaky test teaches everyone to press retry.** A test that fails one run in\ntwenty for reasons unrelated to the change trains the team to rerun instead of\nread. After that, a real failure gets the same treatment. Quarantine the test,\nfix it or delete it, and treat a retry button that gets pressed often as a\nfinding in its own right.\n\n## Further reading\n\n- [Continuous Integration](https://martinfowler.com/articles/continuousIntegration.html)\n  — Martin Fowler's long article: each practice, the ten-minute build, and\n  where the name came from.\n- [Understanding GitHub Actions](https://docs.github.com/en/actions/get-started/understand-github-actions)\n  — workflows, events, jobs and runners as GitHub defines them.\n- [GitLab CI/CD](https://docs.gitlab.com/ci/) — the `.gitlab-ci.yml` file,\n  pipelines, stages, jobs and runners in GitLab's own terms.\n- [pre-commit](https://pre-commit.com/) — checks declared once in a config\n  file, run as Git hooks and again as a step on a CI server.\n- [Task](https://taskfile.dev/) — a `Taskfile.yml` that gives each check one\n  name, so a person and a runner type the same command.\n\n\u003chttps://engineer.company/glossary/ci/\u003e\n","date_modified":"2026-10-20T21:59:50Z","description":"What continuous integration asks of a team, what a CI server adds, what the practice looks like on real projects, and the ways it quietly stops working.","formats":{"gemtext":"https://engineer.company/glossary/ci/index.gmi","gopher":"https://engineer.company/glossary/ci/gophermap","html":"https://engineer.company/glossary/ci/","json":"https://engineer.company/glossary/ci/index.json","markdown":"https://engineer.company/glossary/ci/index.md","pdf":"https://engineer.company/glossary/ci/index.pdf"},"kind":"page","language":"en","title":"What is CI?","url":"https://engineer.company/glossary/ci/","version":1}