Why Woodpecker

Woodpecker runs the lab’s continuous integration. It was not the product of a bake-off. The question was how to stop a bad commit from reaching the main branch, and Woodpecker was already deployed, so the work was proving that it could actually say no.

Drafted by an AI agent (claude-opus-5) from this lab’s own runbooks, deployment log and errata. Reviewed before publication by the site owner. How this site is written →

What was already there

A multi-agent coordination design needed checks on every push: a stale index, a shell script that does not parse, malformed YAML. The obvious alternative was Gitea’s built-in Actions, which has to be switched on and needs a runner host registered against it, so it was new moving parts on a fleet that already had an unfinished CI story. Woodpecker’s server was already up and healthy. The part that looked blocked, a build runner on an isolated network segment that could not reach the management network, did not block the useful half: a checking agent on the git host needs no hole in that isolation.

Proving it could fail

The governance checks were written first and proven locally with three induced failures, each for a different reason: a stale index, an unparseable shell script and malformed YAML. All three returned non-zero.

The server had never had anyone log in, so no repository was enabled and nothing could run. Enabling one needs a browser login through Gitea’s OAuth, which is a credential-creating step an agent cannot perform, so it was left to the human. Getting there took seven blocking layers opened, not the one the plan expected: three firewall rules, two reverse-proxy allowlists, a Gitea setting that restricts which hosts it may call, and an OAuth client secret that did not match.

Then the pipeline was proven in both directions: red at the governance step with a fault in place, green once the fault was removed. A first attempt went red at the clone step and was not counted. A check that fails for an infrastructure reason has shown nothing about whether it can catch a bad commit.

Branch protection waited

The tempting move was to turn on required checks for the main branch in the same sitting. The plan’s own warning stood in the way: a required check that cannot fail is worse than none, because it turns “unvalidated” into “validated” in everyone’s head. Only after the red-then-green proof did the agent test protection itself, on a scratch branch with the main branch untouched.

Creating the rule worked. A merge with a failing check was refused, and a merge with a passing check succeeded. Both directions again, because a gate that only refuses is as untrustworthy as one that only permits.

The trap in the pull request’s mergeable flag

While the merge was being refused for a failing check, the pull request’s mergeable field read true. That field reports git-level mergeability, meaning no conflicts. It says nothing about the policy gate. Tooling that reads it to decide whether a change is ready will be confidently wrong, and only attempting the merge shows the policy’s answer.

Human’s call

Whether to enforce the gate was never a technical question. Protecting the main branch changes the workflow for every agent working in the repository, because direct pushes stop and every change becomes a branch, a pull request and a wait for CI. The agent recommended leaving it advisory first and enforcing once two things were true: the agent running the checks had a liveness monitor, so its silent death could not turn into a fleet-wide inability to merge, and the other working agents had been told. The decision to enforce came from the human, after those held.

What it costs

Every change now waits a minute or two for CI, and the pipeline is a single point of failure for merging. If the checking agent is down, nothing merges, and that can look like the git server being broken. That is why the liveness alert on the agent came before the enforcement and not after it. The emergency path is a procedure and not a standing exemption: confirm the failure is in CI and not in the change, have an admin disable the rule temporarily, merge, re-enable it at once and record it. A permanent bypass list for named agents was rejected as enforcement on the path nobody uses and an exemption on the path everyone does. This site’s own repository now runs the same kind of gate, so a publish pipeline change goes through the same red-then-green discipline.

What would change the decision

If Gitea Actions’ runner story became simpler than maintaining a separate CI server and its OAuth integration, folding CI into the forge would remove a service. The reason it has not is that the checks work and the surrounding alerting has been built around the current server.