werkator/docs/adrs/0007-2026-08-28.build-definitions.md

Build Definitions Replace Branch-Owned Schedules

Status:

• proposed: 2026-08-28
• accepted: 2026-08-28
• rejected: -
• superseded: -

Decision [accepted]: A top-level builds section defines named builds (jobs) with onPush/atTimes triggers and a branch selector — the branch-owned autoBuild schedule and the v0.9.13 per-slot buildCommand/name syntax are replaced by it. branches stays what it is: per-branch build settings that every build inherits.

Context and Problem Statement

Werkator's configuration is branch-centric: branches.<name> holds the build settings, and the nightly schedule (autoBuild) hangs off the branch. v0.9.13 added a per-slot buildCommand and name to autoBuild.times[], so a nightly slot could run a fuller check recorded in its own result pool. That worked, but it is a job concept hidden inside a schedule entry: the slot carries a command, an identity, and (implicitly) a branch — everything a job has, in the wrong place.

Requirements that the branch-centric schema cannot express cleanly:

• Several builds of the same branch with different commands (quick check on push, full PIT test nightly).
• One scheduled build over a set of branches, e.g. "run piTestFull nightly for every branch that had commits in the last 24 hours" — a schedule owned by a branch cannot select branches.
• A name for such a build that is not welded to a single schedule slot.

Technical Background

Since v0.9.13 the result model already carries a pool identity per build (BuildResult.name), with name-keyed history, retention, branches-view rows, and permanent latest-green links, while everything git-side (origin lookups, pruning, worktrees, Gitea) stays keyed by the real branch. So the persistence and UI side is prepared; what is missing is a first-class job in the configuration and the watcher.

Considered Options

• Keep extending the branch-owned autoBuild (status quo of v0.9.13)
• Top-level builds section with named build definitions (jobs)
• Both concepts permanently in parallel

Keep Extending autoBuild

Every new need (per-slot command, per-slot name, branch selectors) grows another attribute inside autoBuild.times[].

Advantages

• No schema change, no migration.

Disadvantages

• The slot is a job in disguise; each extension makes the disguise worse.
• A schedule owned by one branch can never select other branches (activeWithin is inexpressible).
• Two buildCommand keys at different nesting levels with override semantics (the complaint that triggered v0.9.13's rework already).

Top-Level builds Section (chosen)

branches:            # unchanged: per-branch build settings, worktree-overridable
  default:
    cleanCommand: rm -rf build
    buildCommand: ./gradlew --console=plain --no-daemon prQuickCheck

builds:
  # implicit when omitted or not overridden — exactly the pre-builds behavior:
  # default:
  #   onPush: true
  pitest:
    atTimes: ["01:00"]                     # UTC HH:MM, plain strings only
    activeWithin: 24h                      # only branches with commits in the last 24h
    # branches: ["master"]                 # alternative/additional explicit selector
    buildCommand: ./gradlew -PfullPitTest --console=plain --no-daemon piTestFull

A build definition has:

• Triggers: onPush: true|false (default false; the implicit default build has true) and atTimes: [HH:MM, …] (default empty). A build may have both.
• Branch selector: branches: [names] (default: all origin branches) and activeWithin: <duration> (default: unset = no age filter; a branch qualifies while its origin head commit is younger than the duration). Both combine as an intersection.
• Build-setting overrides: buildCommand, cleanCommand, artifactDirs, stdoutLog/stderrLog, and the docker image keys (image, dockerfile, context, env) — anything unset falls back to the merged branch settings.

Semantics:

• Merge order for the effective settings of one build on one branch: config defaults → branches.default → branches.<branch> → the worktree's committed .werkator.yml (build keys, pinned keys stripped) → builds.<name> overrides. The build definition wins last because it is the job; it comes from the repo install/project config (server-side), never from the worktree.
• Pool identity: the default build records under the branch name (URLs, rows, retention as before); every other build records under <branch>@<build> (URL-sanitized, e.g. /branches/master_pitest/…). Each pool keeps its own retention count, latest status, and permanent latest-green link.
• Persistence: the result stores the build's name (build, default default) next to the branch; the derived pool name keeps keying grouping and display. The v0.9.13 buildCommandOverride field is dropped: restart, retry, and startup recovery re-resolve the command from the current config by (branch, build) — a job definition in config is the source of truth, so a re-run of an old result uses the job's current command.
• Triggers in the watcher: onPush uses the existing change detection per pool ("already built" per pool and commit); atTimes fires once per day per slot per pool (state file keyed by pool, date, time). The branches.<name>.requirePullRequest gate stays a branch property and gates all watcher-triggered builds of that branch, as today.
• Execution invariants unchanged: every build of a branch runs in that branch's worktree, at most one build per branch at a time, executor.maxConcurrent across branches, Gitea commit status per commit in the shared status context (last build of a commit wins).

Compatibility and migration:

• No builds section, or no default entry: the implicit default build (onPush: true, all branches) preserves today's behavior exactly. Defining other builds does not disable it; builds.default.onPush: false does.
• branches.<name>.autoBuild (enabled + plain times) keeps working for compatibility, internally mapped to a scheduled build of the branch's own pool, with a deprecation warning in the log; removal is not scheduled.
• The v0.9.13 per-slot buildCommand and name are removed (not deprecated): released one day ago, configured nowhere.

Advantages

• Jobs are first-class: name, command, schedule, and branch selection in one place, no nesting tricks.
• Expresses the previously impossible selector cases (activeWithin, explicit branch lists) naturally.
• Reuses the v0.9.13 pool plumbing (result name, retention, rows, permalinks) almost unchanged.
• The trigger keys read as English: onPush, atTimes.

Disadvantages

• The biggest config-schema change since the rewrite: watcher enqueue logic, config layering, docs, init templates, and tests are all touched.
• Two sections (branches, builds) must be explained: settings per branch vs. jobs over branches.
• Re-runs follow the current job definition instead of the recorded command — a deliberate semantic change against v0.9.13.

Both Concepts Permanently

Keep autoBuild (including the v0.9.13 slot syntax) forever next to builds.

Advantages

• Nothing ever breaks.

Disadvantages

• Two ways to express the same job, forever; every future feature must be specified against both.

Decision Outcome

Top-level builds with onPush/atTimes, as specified above. branches.*.autoBuild stays as a deprecated, mapped alias; the v0.9.13 slot extras are reverted.

Follow-up (2026-08-28): mixing the execution key maxConcurrent into the builds section as a reserved key proved confusing — it is not a build definition. The concurrency limit moved to executor.maxConcurrent (a new section for execution settings), without a compatibility alias, so the builds section holds build definitions only.

Follow-up (2026-08-29): pinning the whole builds section against the branch layer was wrong and is reverted. A branch's committed .werkator.yml describes that branch's CI, and a new builds configuration can only be tried out by committing it on a branch — pinned, it was neither effective at build time nor visible to the watcher, so the job silently did not exist. The branch layer now carries builds too: the watcher reads each origin branch's committed config (git show, cached by head commit) to decide which of that branch's builds are due, and a branch's definitions are evaluated for that branch alone, so they can never trigger builds of another branch. The pinned set is reduced to what does not describe this branch's build: secrets (git), the host/repository sections (server, gitea, executor, watcher), the sandbox policy (docker.enabled/docker.network), and the trust gate (requirePullRequest). Letting a branch set its own buildCommand through a definition grants no new power — branches.*.buildCommand always allowed exactly that — whereas the sandbox and the gate decide whether untrusted branch code runs on the host at all, and therefore stay server-side.