mhoennig
f0f996a53c
`onPush`, `atTimes`, `branches`, and `activeWithin` move into a nested `trigger`. The split is structural on purpose: the inheritance from `builds.default` now subtracts one key instead of a list of four, so a selector added to `TriggerConfig` later is non-inheritable by construction rather than because someone remembered to extend the list. A definition still writing those keys flat is refused by name, per file and scoped like the version check — the machine and project config abort the start, a branch's committed config fails only that branch. Ignoring them would leave the build with no trigger at all, which is a job that quietly stops running: the failure this refusal exists to prevent. Two more things a definition can now say: - A `!` prefix in `trigger.branches` excludes, and an exclusion wins whatever the order. `["*", "!master"]` gives one branch a build of its own without the default build running over it as well — until now the only way out of that double build was to drop the second definition's push trigger. - `statusContext` overrides the Gitea check this build reports as, empty keeping the repository-wide one. Two builds of a commit shared a context and overwrote each other's result, so a quick check beside a long build was not readable in Gitea. Pinned like `requirePullRequest`: a branch that could pick its context could take over the check a branch protection rule depends on. Fixed on the way: a branch whose builds all belong to named definitions rendered an empty row in the branches view, reading as "never built" directly beside its real builds. That row was unreachable before the exclusion patterns made such a branch possible.
97 lines
5.6 KiB
Markdown
97 lines
5.6 KiB
Markdown
# GitTally Rewrite Plan
|
||
|
||
This directory contains the step-by-step plan for rewriting `legacy/gitTally` (bash) as the Kotlin/Spring application in this repository.
|
||
Each step file is self-contained and sized for one focused Claude Code session.
|
||
|
||
## How to Execute a Step
|
||
|
||
Start a fresh Claude Code session and prompt, for example: "Execute docs/plan/01-build-state-domain.md".
|
||
The executing session should:
|
||
|
||
1. Read this file, `00-legacy-analysis.md`, and the step file.
|
||
2. Read the referenced parts of `legacy/gitTally` only if the step file says so.
|
||
3. Implement with tests, following `CLAUDE.md` conventions.
|
||
4. Run `./gradlew ktlintFormat` and then `./gradlew build` until green.
|
||
5. Update the step's checkbox below and note deviations inside the step file.
|
||
|
||
## Guiding Principles
|
||
|
||
- The legacy script defines intended behavior, but it is buggy — treat it as a reference, not a spec.
|
||
- Fix the two known legacy defects by design, not by patching:
|
||
- Build status must be observable while a build runs (event-driven status transitions, async build execution).
|
||
- The web UI must never get stuck loading (JSON status endpoints with explicit error states instead of regex-rewritten HTML).
|
||
- Do not port orphaned or half-implemented legacy config options (see `00-legacy-analysis.md`).
|
||
- Every step leaves the build green and the application runnable.
|
||
- Config keys added by a step must be updated in three places: `GitTallyConfig`, the `InitCommand` templates, and `docs/configuration.md`.
|
||
|
||
## Proposed Architecture Decisions
|
||
|
||
These are proposals baked into the steps.
|
||
Revisit them in an ADR if a step uncovers problems.
|
||
|
||
- Build results are persisted as a JSON file under `.git/gittally/`, behind a `BuildResultRepository` interface (no database, but replaceable).
|
||
- Builds run concurrently up to `builds.maxConcurrent` (default 1), but never more than one build per branch at a time.
|
||
Each branch builds in its own reusable git worktree under `.git/gittally/worktrees/`, checked out detached at the requested commit — never in the primary checkout.
|
||
A later step must decide (possibly per config) whether a new commit on a branch cancels that branch's running build or waits for it; for now new builds queue behind the running one.
|
||
- Artifacts stay on the filesystem, served by the Spring server.
|
||
- The web UI is server-rendered HTML plus small JavaScript polling JSON endpoints (no SPA framework).
|
||
- The watcher is a Spring-managed scheduled component, decoupled from the build executor via the result repository and events.
|
||
- nginx/Let's Encrypt container management is NOT ported; deployment behind an existing reverse proxy is documented instead.
|
||
Revised after step 12 (ADR 0005): an opt-in managed nginx/TLS container is required for Hostsharing container hosts — see step 13.
|
||
|
||
## Steps
|
||
|
||
Foundation:
|
||
|
||
- [x] `01-build-state-domain.md` — build result domain model and persistent repository
|
||
- [x] `02-git-gateway.md` — full git access layer (fetch, branches, commits, checkout)
|
||
- [x] `03-gitea-client.md` — Gitea API client for commit statuses
|
||
|
||
Core engine:
|
||
|
||
- [x] `04-build-executor.md` — async build execution with logs, cancellation, status transitions
|
||
- [x] `05-artifact-store.md` — artifact persistence, naming, retention
|
||
- [x] `06-watcher.md` — branch watching, scheduling, auto-builds
|
||
|
||
Server and UI:
|
||
|
||
- [x] `07-server-mode.md` — `server` subcommand, REST/JSON endpoints, artifact serving
|
||
- [x] `08-web-ui.md` — HTML views with robust live updates
|
||
- [x] `09-system-metrics.md` — system resource monitoring page
|
||
|
||
Completion:
|
||
|
||
- [x] `10-cli-commands.md` — CLI build/status commands
|
||
- [x] `11-docker-build-runtime.md` — optional Docker build execution
|
||
- [x] `12-deployment.md` — systemd service, migration from legacy, docs
|
||
|
||
Added after the initial plan (ADR 0005):
|
||
|
||
- [x] `13-nginx-tls.md` — opt-in managed nginx/TLS container for hosts without a reverse proxy
|
||
|
||
Added after the 2026-08-10 overhead measurements on vm2176:
|
||
|
||
- [ ] `14-build-phase-timing-and-overhead.md` — per-build phase timing, overhead budget warning, ownership/metrics fixes — deferred until after step 15; revisit relevance on vm4006
|
||
|
||
Added for the vm2176 → vm4006 migration (2026-08-10):
|
||
|
||
- [x] `15-runtime-bundle-distribution.md` — self-contained runtime bundle (jlink JRE + jar) for hosts without a Java runtime
|
||
- [x] `16-git-in-docker-builds.md` — read-only git metadata inside Docker build containers, with `.git/gittally/` masked
|
||
|
||
Added after v0.9.19 replaced the per-branch settings with build definitions (2026-08-29):
|
||
|
||
- [ ] `18-remove-branches-section.md` — delete the legacy `branches` section and its `autoBuild` schedule; run around 2026-09-05, after the precondition check in the step file
|
||
|
||
Added for running GitTally on Hostsharing Managed Webspaces (2026-08-10):
|
||
|
||
- [ ] `17-bwrap-build-runtime.md` — GitTally on a Managed Webspace: bubblewrap user-namespace build sandbox with a prepared rootfs (precondition check first — see the step file), plus web access under a domain via the platform's Apache proxy and Let's Encrypt
|
||
|
||
Steps 01–03 are independent of each other.
|
||
Steps 04–06 depend on 01–03.
|
||
Steps 07–09 depend on 04–06.
|
||
Steps 11 and 12 are optional/deferrable; 10 only needs 04–06.
|
||
Step 13 depends on 07, 11, and 12.
|
||
Step 15 depends on 12 and 13 and revises the containerized-runtime sketch in `docs/bootstrapping.md` (ADR 0006 is written as part of the step; GraalVM native image was evaluated and rejected there).
|
||
Step 17 depends on 11, 15, and 16, and starts with a hard precondition check on the target webspace (ADR 0007 is written as part of the step).
|
||
Step 18 depends on nothing in code but on the watched repository having migrated — its precondition check is a hard gate, not a formality.
|