On the first morning in a large team, a developer who has always worked alone finishes a small fix and types what has always worked: git push origin main. The repository host refuses the push. The main branch is protected, and changes reach it only through a pull request.
That refusal is not friction. It is the first of the team's rules doing its job, and pushing straight to main is a habit from solo work that this rule exists to stop. Alone, a bad push costs its author an hour. In a team of hundreds that shares one main branch, a bad push turns main red, and while main is red nobody can merge. On the day this site follows, main stays red for 72 minutes even though every rule below was in place. Times and counts on this page are illustrative.
Alone, you are the gate. In a team, the repository is the gate. Learn where each rule lives, and you can read any team's pipeline in an afternoon.
1. What changes when you are not alone#
Working alone, one person does every job around a change. You write it, you read your own diff, you run the tests when you remember, you decide when it ships, and you fix main when it breaks. That works because every decision sits in one head, and one head remembers what it changed.
A team of hundreds has no such head. Nobody knows every file, nobody sees every change, and two changes that each work can fail together. So each job that a solo developer did from memory has to move somewhere that does not depend on memory: a rule on the repository host, a file in the repository, a named owner, or a machine in CI (continuous integration, the shared machines that build and test every change).
| Working alone | In a large team | Why the team needs it |
|---|---|---|
| Push to main | Main is protected. Every change arrives through a pull request. | One bad push would stop hundreds of people. |
| I read my own diff | Someone else approves, and for some paths a named owner must. | The author is the person least able to see the mistake. |
| I run the tests when I remember | Required checks run on every pull request. Merge is blocked until they pass. | A rule that depends on memory fails at volume. |
| My machine is the truth | CI is the truth. "It works on my machine" is not evidence. | Machines differ. CI is the one place everyone shares. |
| One build at a time | A merge queue tests each change together with the changes ahead of it. | Two changes that each pass alone can fail together. |
| I know every file | An owners file says who must approve which folder. | Nobody knows the whole repository. |
| Something broke: I fix it on main | Something broke: revert first, fix later in a new pull request. | While main is red, nobody can merge. |
| Secrets live in my shell | Secrets live in CI, and a job gets only the ones it needs. | A pull request can contain anyone's code. |
Read down the middle column and one pattern shows: every rule is written down where a machine can apply it. A coding agent changes none of these rules. It raises the number of changes that pass through them, about 300 pull requests a day at the team this site follows, and that is why each rule must run without a person in the loop.
2. Seven rules, in the order one change meets them#
The team on this site is Acme, a fictional software company with one large repository: a web app, a public REST API and backend services. Its rules are easiest to understand by following one change through them. The change is work item ORD-2187: add an optional field, delivery_note, to the order API, so a customer can leave delivery instructions. It becomes pull request #4812, and it meets seven things somebody set up once.
At 09:14, while the agent edits. The developer gives the task to a coding agent. Before any commit exists, the agent's harness (the software that runs the agent, executes its tools and fires its hooks) runs hook scripts at fixed moments: a lint check after each edit, and the affected tests before the agent stops. These rules come from agent settings and hooks committed to the repository, in .claude/, together with git hooks in .githooks/. The same folders hold the skills (a skill is a file of instructions for one kind of task) and agent definitions that the pipeline's own agents load, so one set of files serves the developer's machine and CI.
At 09:34, at the push. The developer runs the team's ship skill, which pushes the branch feat/order-delivery-note and opens the pull request. Pushing to a branch is allowed; pushing to main is not. That is the branch rule on main: no direct push except for actors on a bypass list, and a merge only through a pull request that meets every condition below.
At 09:35, when the lane is computed. Not every change needs the same review. Acme sorts each pull request into a green, yellow or red lane by what it can break, using the lane rules in .github/lanes.yml. #4812 is red because it touches two high-risk paths: the public API contract and a database migration. Paths set the minimum lane, and the author never chooses it. The owners file, CODEOWNERS, then names who must approve those paths: the API owners and the data owners. How lanes work is explained on Review.
From 09:36 to 10:48, in the checks. Five required checks gate the merge: unit-tests, integration-tests, lane, agent-review, and e2e-smoke, which runs only in the merge queue and reports success at once on the pull request. agent-review is the check that runs a reviewer agent and posts its findings as comments. A sixth check, affected-tests, runs on every pull request but is not required, because a wrong map of which tests a file affects can skip the one test that would have failed. The nightly full run is its net.
At 10:50, in the merge queue. Approved changes do not merge one by one. The merge queue builds each change on top of the ones waiting ahead of it and tests the combination before main moves. #4812 joins four other pull requests, the group passes the queue's end-to-end smoke test at 11:02, and all five merge. How the queue builds, and what it does when a change fails, is on CI/CD.
Throughout, in CI. Every job above runs with credentials that CI hands it. CI identity and secrets decide what each job can reach: the reviewer job gets the key it needs to call the model, and no job that runs pull request code gets a credential that can deploy. At Acme the model key is an API key in the CI secret store, passed only to the jobs that call the model. A short-lived identity issued through the cloud provider is the stronger option where the model is served that way; CI/CD agents states the standard.
| # | What | Where it lives | What it does | Read more |
|---|---|---|---|---|
| 1 | Agent settings, hooks, skills and agent definitions | .claude/, .githooks/, agents/ | Fast feedback on the developer machine, and the same files drive the agents that run in CI | Code change, Hooks, CI/CD agents |
| 2 | Branch rule on main | Repository settings, set by an administrator | No direct push, except for actors on a bypass list. Requires a pull request, the required checks, owner review and the merge queue. | Review |
| 3 | Lane rules | .github/lanes.yml | Sorts each pull request into green, yellow or red by what it can break | Review |
| 4 | Owners file | CODEOWNERS | Maps folders to the people who must approve changes there | Review |
| 5 | Required checks | Workflow files in .github/workflows/ | unit-tests, integration-tests, lane, agent-review, e2e-smoke. Each reports pass or fail on the pull request, and in the merge queue. | CI/CD |
| 6 | Merge queue | Repository settings | Tests the combination of waiting changes before main moves | CI/CD |
| 7 | CI identity and secrets | CI settings | Gives each job only the credentials it needs. A job that runs pull request code gets none that can deploy. | CI/CD agents |
Parts 2 and 6 are settings on the repository host, and part 7 lives in CI settings. The other four are files in the repository. That has a consequence worth stating as a rule: a change to any file that decides how other changes are judged must go through the same pipeline, in the red lane, with its owner's approval. Otherwise the fastest way to pass a check would be to edit it.
3. Where each rule lives in the repository#
A new joiner who knows the seven rules can find each one in the tree below. The files near the top, the gate files, decide how other changes are judged or what an agent loads and may do. The canonical list is .github/ (workflows, lane rules, the active agent versions), CODEOWNERS, CLAUDE.md, .claude/, .mcp.json where a repository has one, .githooks/, agents/ and ci/. A named platform team, @acme/platform-leads, owns them; the triage agent's folder is owned by @acme/triage-owners.
The repository, as a new joiner sees itWhich folder holds which rule
acme/
├── CODEOWNERS who must approve which folder
├── CLAUDE.md instructions every agent session reads
├── .github/
│ ├── lanes.yml lane rules: green, yellow, red
│ ├── agent-versions.yml which version of each pipeline agent is active
│ └── workflows/
│ ├── tests.yml "Run Tests": build, unit-tests, integration-tests,
│ │ affected-tests, e2e-smoke (merge queue),
│ │ e2e-full (push to main), nightly-full (schedule)
│ ├── lane.yml computes the lane from the base branch; sets the label only
│ ├── agent-review.yml the reviewer agent: no edit tools, posts comments
│ ├── agent-fix.yml the fix-on-request agent, when a person asks in a comment
│ └── red-build.yml triage, verify and revert when "Run Tests" fails on main
├── .githooks/ git hooks: pre-commit, commit-msg, pre-push
├── .claude/
│ ├── settings.json agent hooks and deny rules, shared by the team
│ ├── hooks/ the scripts those hooks run
│ ├── skills/ skills every session can use, local and CI (ship, review-rules)
│ └── agents/ subagent definitions (code-reviewer, fix-finding)
├── agents/
│ ├── triage/ the CI triage agent: prompts, skills, tools, evals
│ └── fix/ the red-build fix agent
├── ci/ scripts that the workflows call
├── tools/ shared scripts, such as affected-tests.sh (hook, pre-push and CI)
├── api/openapi/ public API contracts (red path)
├── db/migrations/ database migrations (red path)
├── infra/ infrastructure (red path)
└── services/
├── auth/ payments/ (red paths)
└── orders/ cart/ notifications/
Everything above tools/ is a gate file. No change to a gate file merges without its owner's approval, whoever or whatever wrote it.
Two lines in the tree are easy to misread. lane.yml only computes the lane: it runs from the base branch on pull_request_target (an event that runs the workflow from the default branch), and sets the label. It posts no status. The lane status has one author, the policy app, an automation identity this site proposes as a design: it posts the status as pending, and re-checks the lane each time an approval arrives (Review). And e2e-full sits inside Run Tests on purpose: red-build.yml listens for that workflow failing on main, so a failure in a different workflow would never start the triage agent.
4. What a developer types in a day, and what answers#
The rules above are invisible until a command meets them. The block below is the working day of #4812 as commands. In the running example the agent makes the commit and the ship skill runs the push and opens the pull request; the commands are the same whoever types them. It demonstrates which command hands control to which rule. Running it proves only that the commands are valid; whether the change is right is decided by the checks that answer them.
The commands of one working dayWhat a developer types, and what answers
# once, after cloning
git config core.hooksPath .githooks # turn on the team's git hooks
# start work on a work item
git switch -c feat/order-delivery-note # never work on main
# ... the coding agent edits; its hooks check each edit and the final result ...
git add -A
git commit -m "feat(orders): add delivery_note to the order API" -m "Refs: ORD-2187"
git push -u origin feat/order-delivery-note # pre-push: affected tests once, then the local review
gh pr create --fill # open the pull request
gh pr checks --watch # watch the checks
gh pr view --web # read the findings, posted on the lines they concern
# after the fixes and the approvals
gh pr merge # with a merge queue: joins the queue, or arms auto-merge until the checks pass
| After this command | Who answers |
|---|---|
git commit | Git hooks on the developer machine |
git push | The pre-push git hook, then the repository host, which accepts a branch and refuses main |
gh pr create | The repository host starts every check. The lane is computed. The reviewer agent posts findings. |
gh pr merge | The merge queue. Then the pipeline on main. |
The first line matters more than it looks. Git reads hooks from the folder that core.hooksPath names, and that setting is local configuration, so a clone does not bring it along. Until each clone runs that line once, the team's git hooks do not run on that machine. Git hooks are a guard for the developer, not a gate: anyone can skip them with --no-verify, which is why the required checks run again on the server.
5. One change, start to finish#
Each rule can be explained on its own, but the team only works if they hand over to each other in order. The diagram shows the stages of one change and which check lives at each. The further right a problem is found, the more people and machines it has already cost.
Diagram: The path of one change · each stage and where its checks live
Read left to right. Each column is a stage. The top box is what happens; the boxes under it are the checks this site puts there. The further right a problem is found, the more it costs. Click any box.
- 1 · Code change
- Agent edits files: The coding agent reads and edits files to do the task.
- Check after each edit: A hook runs ruff on the changed file and sends failures back to the agent.
- Tests before it stops: A stop hook runs the type check and the affected tests. Red tests send the agent back to work once.
- 2 · Commit
- Commit and push: The agent stages, commits and pushes its own branch.
- Guard before the push: An agent hook and deny rules stop secrets, protected paths and force pushes.
- Server rules: Branch rules, required checks and code owners on the repository host. Code owners on the workflow files keep a pull request from rewriting its own checks. The gate to rely on.
- 3 · Pull request
- Review before opening: A headless review of the diff before anyone else is notified: on the developer machine for feedback, on a trusted runner for a verdict.
- Signed review receipt: A record of exactly what a trusted runner reviewed. CI verifies the signature and the inputs instead of repeating the review.
- Pull request with evidence: Intent, lane, tests run, findings fixed or declined, risk note.
- 4 · Review
- Lane from changed paths: CI computes green, yellow or red from what the change touches.
- Reviewer agent on everything: An agent with no edit tools, in a fresh context, reports a few verified findings.
- People on yellow and red: One approval for yellow. The named owner, with a reviewed plan, for red.
- 5 · CI/CD
- Merge queue, cheap tier first: Each change is tested on top of those ahead of it. Unit tests, then integration tests, before any end-to-end environment.
- Scarce environments, by class: End-to-end runs only for changes that passed everything else, with a share and a maximum wait per class.
- Deploy and watch: Only after e2e-full passes on that main commit; then a progressive rollout. A person decides on rollback.
Here is the whole day of #4812, with the page that explains each step. Read it as a map of the rest of the site.
| Time | What happens | Who acts | Page |
|---|---|---|---|
| 09:12 | The developer gives the agent the task from ORD-2187 | The developer | Code change |
| 09:14–09:31 | The agent edits six files. A hook catches a lint error after the second edit. When the agent stops, another hook runs the affected tests; one fails, the agent fixes it, and 14 pass. | The model; the harness runs the hook scripts | Code change |
| 09:33 | The agent commits. The git hooks pass. | The agent; git | Commit |
| 09:34 | The branch is pushed and the pull request opens | The developer, through the ship skill | Pull request |
| 09:35 | The lane is computed: red, because the change touches a public contract and a migration | A CI job from the base branch | Review |
| 09:40 | The reviewer agent posts two findings | The reviewer agent | Review |
| 09:44 | Finding 1, a missing length check, is fixed in a new commit | The fix-on-request agent, asked by the developer | Review |
| 10:20 | Finding 2 would break existing clients. An API owner decides the field must be optional; the agent applies it. | A person, then the agent | Review |
| 10:48 | An API owner and a data owner approve. The lane check passes. | Two people | Review |
| 10:50–11:02 | The merge queue tests it with the four changes ahead. All five merge. | The repository host; CI | CI/CD |
| 11:46 | The wider end-to-end run on main, e2e-full job 4411, fails | CI | CI/CD |
| 11:55 | A triage agent names #4812 as the likely cause, confidence 0.82 | The CI triage agent | CI/CD |
| 12:35 | Three re-runs with no model support the claim | The verifier | CI/CD |
| 12:36–12:58 | A script opens the revert #4840; an API owner approves it; it passes the queue. Main is green. | A script; a person; the queue | CI/CD |
| After 12:58, and the next day | The red-build fix agent stops and hands over two valid repairs. The notifications team chooses one; the next day the developer, with a coding agent, writes the fix pull request through every stage. | An agent; people | CI/CD |
Up to 12:58, people made five decisions: the task, the request to fix finding 1, the contract decision, the owners' approvals, and the approval of the revert. They also ran two routine steps, starting the ship skill and passing the owner's decision to the agent. Everything else ran by rule. And because production deploys only after e2e-full passes on that exact commit, #4812 was on main for under two hours and never deployed.
6. If you are joining such a team#
The fastest way into a team like this is to find its rules before your first change meets them. The list below is in the order that pays off soonest.
| # | In your first week | Why |
|---|---|---|
| 1 | Read CODEOWNERS and the lane rules | They tell you which of your changes will need whom |
| 2 | Open three merged pull requests: one small, one large, one reverted | You see the real checks, the review style and what a revert looks like |
| 3 | Turn on the git hooks (git config core.hooksPath .githooks) and confirm they fire | A clone does not bring the setting along |
| 4 | Find the list of required checks on main | These are the gate. Everything else is advice. |
| 5 | Learn how to read a failed check: where the log is, how to re-run | You will need it on day two |
| 6 | Ask what the merge queue does on failure | Removed and re-queued, or batch split. It changes how you react. |
| 7 | Find the flaky-test list and its owner | So you can tell a real failure from a known one |
| 8 | Read the agent settings in the repository, .claude/settings.json | They show what the agent may not do here |
| 9 | Make your first pull request small, in paths the lane rules put in yellow | You learn the path with little at stake |
| 10 | Find out who is on call for main | That person decides when main is red |
7. If you are the one setting it up#
Turning everything on at once leaves nothing to measure against, and the first wrong call discredits all of it. The order below adds one rule at a time, and each step has a number to watch before the next. It is the short form of the plan on Adopt, which adds two later steps: signed review receipts and the checks for a change to an agent.
| Order | Turn on | Watch before the next step |
|---|---|---|
| 1 | Nothing yet: count the baseline | Pull requests, review wait, end-to-end runs per merged change, escaped defects |
| 2 | Agent hooks and git hooks in the repository | Share of CI failures that a local check would have caught |
| 3 | Branch rule, required checks, and an owners file for the gate files and other high-risk paths | No change to a gate file merges without its owner |
| 4 | The reviewer agent, as advice only | Share of its findings that lead to a code change |
| 5 | Lanes, computed in shadow first, then green merges with no person | Green-lane changes that the weekly audit says should not have been green |
| 6 | Merge queue, tiered pipeline and the agent retry budget | End-to-end runs per merged change, and the queue failure rate |
| 7 | The red-build loop: triage that only records, then the verifier, then revert pull requests a person merges | Share of triage claims the verifier supports, and minutes main stays red |
8. Side questions#
| Question | Short answer |
|---|---|
| Is this GitHub only? | No. GitLab, Bitbucket and others have the same parts under other names: merge requests, approval rules, merge trains. |
| One large repository or many small ones? | The rules are the same. In one large repository the build cache and test selection matter more; with many, changes that span repositories matter more. |
| Does a small team need all of this? | No. Under about 30 pull requests a day (an illustrative line, not a measured one), a branch rule, required checks and one approval are enough. Add the rest when a number tells you to. |
| Who owns the gate files? | A named platform team. If everyone owns them, the fastest way to pass a check is to change it. |
| What is a changelist, or CL? | Another word for one change sent for review. Some companies say CL where others say pull request. |
The refused push on the first morning holds the whole idea. Alone, the only thing between a change and main was the author's judgment, and that was enough because the author was the only one affected. In a team, the judgment has to be written down where a machine applies it every time, and the files that hold it need an owner, because they are the one change that can weaken every other check. Each stage page that follows is about one of these rules: what it can see, what it costs to run, and what it still cannot prove.
Next: the first of those rules meets #4812 at 09:14, inside the agent's editing loop, before any commit exists. Code change.