Renaming gitTally to Werkator because there is another git-related tool named gittally (#1)
* renaming from gitTally to Werkator * Rename GitTally to Werkator `gitTally` is the name of another product in the git space, so the rename is a precaution; nothing about what the build system does changes. The name follows one rule: `Werkator` where it is prose, capitalized where it is a Kotlin type and its file, lowercase everywhere a machine reads it — the command, packages, paths, configuration keys and values, the Gitea check context. Environment variables keep their convention and are uppercase throughout. Every configuration file is still found under its pre-rename name (`ConfigFiles`): `.gittally.yml` at the repository root, in a build worktree and as committed on a branch, `.git/gittally/.gittally.yml` for the machine layer. The current name wins where both exist, and the old file is then ignored rather than merged — two files side by side are a half-done rename, not a layering. Without the fallback an installation that updated without renaming would not fail: a configuration that is not found leaves every setting at its default, so it would come up looking healthy while having forgotten its credentials and its builds. `docs/werkator-migrationsplan.md` lists what the fallback does not cover and has to be moved by hand — above all the state directory `.git/werkator/`, which holds the build history, the control token and the worktrees, and has no fallback of its own. `docs/migration-from-legacy.md` is deleted with this: it mapped the legacy script's environment variables, and every host it addressed has long since moved to the YAML configuration. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> * Move the pre-rename state directory at the first start The configuration is found under either name, the state is not: build history, control token, auto-build slots and worktrees live at one fixed path. An installation that updates without moving `.git/gittally` would not fail — it would come up with an empty history and a fresh control token, quietly. So the first start moves it instead of the release notes asking for it. Only when the old directory exists and the new one does not. Where both exist nothing is touched and a warning names the leftover: which of the two is the live state is not something to guess. A failed move is an error in the log, never an abort — a CI must not hang on it. The worktrees are dropped rather than moved, since they point at their old path in both directions; `GitWorktreeWorkspaces` prunes the stale admin entry and recreates each on its branch's next build. A generated systemd unit moves with the directory and leaves its symlink dangling, which is warned about — the running service is unaffected, the next start is not. Runs from `CliRunner`, before any command resolves a path under the directory, and so before the second context of `server` exists. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> * Document PR#1: the rename to Werkator Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> * Drop the legacy env-to-YAML conversion from the setup tool The old bash script configured itself through `GITTALLY_*` environment variables. The blanket rename rewrote those literals, so the converter was looking for `WERKATOR_*` — a spelling no host has ever written. Fed a real legacy file it would have found nothing and written an almost empty configuration, without an error, which is the same silent failure this rename is otherwise careful to avoid. The conversion has served its purpose with the vm2176 to vm4006 migration, so it goes instead of being repaired. What remains is the setup of a new instance: the preconditions, the credential prompt, and the machine configuration written mode 600 — now carrying the host's public URL as well, since that is host-specific too. Everything the repository builds comes from `init` and its templates. It also stops emitting a legacy `branches:` section, which step 18 is about to reject outright. `docs/plan/00-legacy-analysis.md` and `13-nginx-tls.md` get the real `GITTALLY_*` spelling back: they record what the old script read. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> * Describe this repository's build with a build definition Its own `.werkator.yml` still used the deprecated `branches` section with an `autoBuild` schedule that was switched off. That section is read only while nothing defines a build at all, and step 18 rejects it by name — so this repository would have blocked the precondition of that step, which asks that no configuration still in play carries it. Nothing about the build changes: `builds.default` with `trigger.onPush` is a build of every new commit on every branch, which is what the branch section said. `config:print --full` resolves the definition completely and logs no deprecation warning any more. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> * Stop documenting the pre-rename fallback for users Exactly one repository is configured with the old names, and it is migrated by hand in the same move as this release. The fallback is therefore a transition of days, not a feature anyone reading the release notes or the configuration reference has to plan around. Removed from `releases.html` and `docs/configuration.md`. The mechanism itself is unchanged and stays described where it is worked on: in `ConfigFiles`, in `StateDirMigration`, and in the migration plan. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> * Bring the PR-doc to its final state The `statusContext` question is answered and marked as decided rather than left standing: it is the one value a human reads as a label, and it stays lowercase because Gitea matches it and the client reads it back, which makes it a value. Also records that the pre-rename fallback is deliberately absent from the release notes and the configuration reference. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> * Release v1.0.0: Werkator The release after 0.9.21 is 1.0.0, because a product that changes its name is better off counting from one under it. The release note says as much, so the jump is not read as a claim about maturity — plan steps 14, 17 and 18 are still open. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> * Correct the PR-doc about the version It claimed the PR carries no version bump, which the release commit made untrue, and records why the number is 1.0.0 instead of 0.9.22. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> * Point the legacy references at the history `legacy/gitTally` was removed from the tree with the rename, but the README still described it as a reference kept in the repository, and the plan told an executing session to read parts of it — including step 14, which is open. The README section is gone; `docs/plan/README.md`, step 14 and the legacy analysis now say where the script actually is (`git show 7f55068^:legacy/gitTally`). Executed steps and ADR 0004 keep their wording: they record what was true when they ran. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> * Retarget the links in the historic PR-docs The package rename moved every file the older PR-docs link to, leaving 60 dead links. Only the link targets are rewritten, never the visible text and never a statement: those documents record what was true when they were written, GitTally in the prose included. A snapshot may be outdated; it should still be navigable. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> * Add the v1.0.0 deployment procedure for vm4006 Measured, not estimated: the state directory is 878 MB, of which 878 MB are the nine build worktrees. What cannot be recreated is 84 KB, so the snapshot before an in-place switch is instant and the rollback is one sequence of moves. Records the three expected non-failures — a cold Gradle volume, one image rebuild, containers left under the old label — and that `gitea.statusContext` needs no attention because it comes from the watched repository's committed configuration. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> * Rename the machine configuration along with its directory Found by the deployment to vm4006: the move renames the directory and leaves the file inside it alone, so the machine configuration ended up at `.git/werkator/.gittally.yml` — a pair of names the lookup did not expect, because it pairs directory and file name. The instance resolved empty credentials, no public URL and none of the host's build definitions, and said nothing about it. That is the exact failure this change exists to prevent, produced by the change itself. `StateDirMigration` now renames the configuration with the directory, unless one under the current name is already there. `ConfigFiles` carries `.git/werkator/.gittally.yml` as a third candidate as well, for a directory somebody moved by hand, where the migration never runs and so can rename nothing. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> * Let init see a configuration under its previous name `init --systemd` runs `init`, and its "already exists" check knew only the current name. On the one repository still carrying `.gittally.yml` it therefore wrote a fresh template `.werkator.yml` beside it — and since the current name wins, that repository would have built the template's `./gradlew test` instead of what its own configuration says. Found on vm4006, where the file was created in the watched working tree and removed again by hand. Both checks now ask `ConfigFiles`, so init decides existence by the same rule the loader uses to read. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> * Record the v1.0.0 deployment to vm4006 Deployed from the branch as the final test of PR#1, and it did what a final test is for: it found two silent-failure defects before the service was started, both fixed and redeployed in the same window. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> * Drop the control token left under the old localStorage key The key is named after the product, so the rename left every browser with a token under `gittally.controlToken`, which nothing reads any more and which "forget token" can no longer reach. It is a write-scope token in a browser store, not a password, but a secret nobody owns is worth one line to remove. Removed on load. The token on the server is unchanged, so re-entering it once per browser is all the rename costs. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 5 <noreply@anthropic.com>
This commit is contained in:
Michael Hönnig
co-authored by
Claude Opus 5
Claude Opus 5
parent
4d76744721
commit
d0169e57bc
@@ -1,23 +1,23 @@
|
||||
---
|
||||
name: architecture
|
||||
description: Detailed GitTally subsystem architecture — CLI wiring and exit codes, server mode, web UI, configuration system, git access, build execution (native and Docker), watcher poll cycle, and system metrics. Use when designing or modifying code in the commands, config, git, gitea, build, artifacts, watcher, metrics, or server packages, or when a question goes beyond the overview in AGENTS.md.
|
||||
description: Detailed Werkator subsystem architecture — CLI wiring and exit codes, server mode, web UI, configuration system, git access, build execution (native and Docker), watcher poll cycle, and system metrics. Use when designing or modifying code in the commands, config, git, gitea, build, artifacts, watcher, metrics, or server packages, or when a question goes beyond the overview in AGENTS.md.
|
||||
---
|
||||
|
||||
# GitTally Architecture
|
||||
# Werkator Architecture
|
||||
|
||||
GitTally is a lightweight, declarative CI/CD build system.
|
||||
Werkator is a lightweight, declarative CI/CD build system.
|
||||
It is a dual-mode application: **CLI** (interactive, status, config) and **Server** (HTTP, persistent).
|
||||
|
||||
## Entry Point and CLI Wiring
|
||||
|
||||
Spring Boot starts via `GitTallyApplication`. A separate `CliRunner` component (in the same file) implements both `CommandLineRunner` (runs picocli) and `ExitCodeGenerator` (returns the exit code). `exitProcess` is called only from `main()` via `SpringApplication.exit()` — **never** inside `run()`. This keeps the Spring context alive during tests.
|
||||
Spring Boot starts via `WerkatorApplication`. A separate `CliRunner` component (in the same file) implements both `CommandLineRunner` (runs picocli) and `ExitCodeGenerator` (returns the exit code). `exitProcess` is called only from `main()` via `SpringApplication.exit()` — **never** inside `run()`. This keeps the Spring context alive during tests.
|
||||
|
||||
Picocli commands are Spring `@Component` beans. The root command (`GitTallyCommand`) declares subcommands as class references in `@Command(subcommands = [...])`. Picocli resolves them from the Spring context via the auto-configured `IFactory` bean.
|
||||
Picocli commands are Spring `@Component` beans. The root command (`WerkatorCommand`) declares subcommands as class references in `@Command(subcommands = [...])`. Picocli resolves them from the Spring context via the auto-configured `IFactory` bean.
|
||||
|
||||
```
|
||||
GitTallyApplication ← @SpringBootApplication
|
||||
WerkatorApplication ← @SpringBootApplication
|
||||
CliRunner ← CommandLineRunner + ExitCodeGenerator
|
||||
GitTallyCommand ← root @Command, delegates to subcommands
|
||||
WerkatorCommand ← root @Command, delegates to subcommands
|
||||
commands/
|
||||
InitCommand ← "init [--systemd]"
|
||||
ServerCommand ← "server"
|
||||
@@ -31,27 +31,29 @@ commands/
|
||||
`build` and `retry` run builds through the async `BuildExecutor` but block until completion via `ConsoleBuildRunner`, which streams the live log to stdout and waits for the artifact persist before the JVM exits.
|
||||
Branch arguments resolve legacy-style name fragments (`BranchNameResolution`); the CLI reuses `UiFormats` so console and web UI display the same formats.
|
||||
|
||||
The web application type is set to `none` in `application.yml`, so plain CLI runs never start a web server. The `server` subcommand launches a **second** `SpringApplication` with `WebApplicationType.SERVLET` and the `server` profile, then blocks until shutdown. `application-server.yml` switches the web type (`spring.main.*` properties beat programmatic builder settings), `CliRunner` is `@Profile("!server")` so the second context does not run picocli again, and the watcher poll loop starts only in the `server` profile (`ServerWatcherLifecycle`). The JSON API, artifact serving, and the web UI live in the `server` package; mutating endpoints are guarded by a generated control token under `.git/gittally/control-token`.
|
||||
The web application type is set to `none` in `application.yml`, so plain CLI runs never start a web server. The `server` subcommand launches a **second** `SpringApplication` with `WebApplicationType.SERVLET` and the `server` profile, then blocks until shutdown. `application-server.yml` switches the web type (`spring.main.*` properties beat programmatic builder settings), `CliRunner` is `@Profile("!server")` so the second context does not run picocli again, and the watcher poll loop starts only in the `server` profile (`ServerWatcherLifecycle`). The JSON API, artifact serving, and the web UI live in the `server` package; mutating endpoints are guarded by a generated control token under `.git/werkator/control-token`.
|
||||
|
||||
## Web UI
|
||||
|
||||
The UI is server-rendered Thymeleaf (`UiController`, templates under `src/main/resources/templates/`) plus one hand-written JavaScript file (`static/gittally.js`) — no SPA framework, no frontend build pipeline. Pages render the full state server-side; the script then polls the JSON API and re-renders table bodies from data. Every fetch has a timeout and failures flip an explicit error badge — never re-fetch and diff whole HTML pages, and never leave a spinner without an error path (the legacy defect). Polling pauses while the tab is hidden. `UiFormats`/`gittally.js` must produce the same display formats (timestamps, durations).
|
||||
The UI is server-rendered Thymeleaf (`UiController`, templates under `src/main/resources/templates/`) plus one hand-written JavaScript file (`static/werkator.js`) — no SPA framework, no frontend build pipeline. Pages render the full state server-side; the script then polls the JSON API and re-renders table bodies from data. Every fetch has a timeout and failures flip an explicit error badge — never re-fetch and diff whole HTML pages, and never leave a spinner without an error path (the legacy defect). Polling pauses while the tab is hidden. `UiFormats`/`werkator.js` must produce the same display formats (timestamps, durations).
|
||||
Two independent staleness signals, never merged: the `live-indicator` badge says whether *this browser* reaches the server, and the `watcher-banner` (fed from `/api/watcher`, in the shared `nav` fragment) says whether the *server* reaches origin — a watcher that cannot fetch leaves the server perfectly reachable and every row stale.
|
||||
|
||||
## Configuration System
|
||||
|
||||
GitTally is configured by two YAML files, deep-merged by `ConfigLoader` (later wins):
|
||||
Werkator is configured by two YAML files, deep-merged by `ConfigLoader` (later wins):
|
||||
|
||||
1. `.gittally.yml` at the repo root — committed, shared team settings.
|
||||
2. `.git/gittally/.gittally.yml` — not committed; machine-specific overrides and secrets (`git.account`, `git.token`).
|
||||
1. `.werkator.yml` at the repo root — committed, shared team settings.
|
||||
2. `.git/werkator/.werkator.yml` — not committed; machine-specific overrides and secrets (`git.account`, `git.token`).
|
||||
|
||||
On top of those comes the **branch layer**: the `.gittally.yml` committed on a branch, applied by `loadWithBranchLayer` (the watcher passes the content read via `git show`, `loadForWorktree` the file in the build worktree). A branch describes its own CI and wins over both layers — the whole `builds` section — so a configuration can be tried out on a branch without touching other branches' builds. `stripPinned` removes what is not a description of this branch's build: `git`, `server`, `gitea`, `executor`, `watcher`, and — inside every `builds` definition as well as every legacy `branches` entry — `requirePullRequest`, `statusContext`, and `docker.enabled`/`docker.network`.
|
||||
Every lookup falls back to the pre-rename name (`ConfigFiles`): `.gittally.yml`, and `.git/gittally/.gittally.yml` for the machine layer. Current name first, and where both exist the old one is ignored rather than merged — a missing config is not an error, so an un-renamed installation would otherwise start on defaults without a single failure.
|
||||
|
||||
Each file is version-checked before merging (`gitTally.version.since`/`below`, `ConfigVersions.verdict`), so the message can name the file to fix: `since` is hard in both directions — too old a GitTally, or a file written before `ConfigVersions.FORMAT_BROKE_IN` and read after it — while `below` only warns. There is no format version (`apiVersion`) on purpose: only one configuration generation is supported, and the declared version exists to make the incompatibility nameable.
|
||||
On top of those comes the **branch layer**: the `.werkator.yml` committed on a branch, applied by `loadWithBranchLayer` (the watcher passes the content read via `git show`, `loadForWorktree` the file in the build worktree). A branch describes its own CI and wins over both layers — the whole `builds` section — so a configuration can be tried out on a branch without touching other branches' builds. `stripPinned` removes what is not a description of this branch's build: `git`, `server`, `gitea`, `executor`, `watcher`, and — inside every `builds` definition as well as every legacy `branches` entry — `requirePullRequest`, `statusContext`, and `docker.enabled`/`docker.network`.
|
||||
|
||||
After merging, `resolveBuildSections` decides which section describes the builds: `builds` or the legacy `branches`, never both. With no real build definition (`builds.maxConcurrent` is not one, `dropNonDefinitionBuilds` already drops it) the legacy path runs and `branches.default` is merged into every other branch entry; otherwise `branches` is dropped with a warning and `mergeBuildDefaults` applies `builds.default` as the base of every other definition — its settings only, never its `trigger` block (`TRIGGER_KEYS`, a single key so that a selector added to `TriggerConfig` later is non-inheritable by construction). `checkTriggerBlocks` refuses a definition still writing `onPush`/`atTimes`/`branches`/`activeWithin` flat, per file and scoped like the version check. Deciding this on the merged map is deliberate: a build defined on a branch and unknown to the host still inherits the host's `builds.default`, sandbox policy included, which is what keeps the pinned keys effective for it. The result is bound to the `GitTallyConfig` data classes (`config/GitTallyConfig.kt`), which define the schema and all defaults; `GitTallyConfig.buildSettings(branch, build)` is the single answer to "what does this build run".
|
||||
Each file is version-checked before merging (`werkator.version.since`/`below`, `ConfigVersions.verdict`), so the message can name the file to fix: `since` is hard in both directions — too old a Werkator, or a file written before `ConfigVersions.FORMAT_BROKE_IN` and read after it — while `below` only warns. There is no format version (`apiVersion`) on purpose: only one configuration generation is supported, and the declared version exists to make the incompatibility nameable.
|
||||
|
||||
Three places must stay in sync when config keys change: the `GitTallyConfig` data classes, the commented templates generated by `InitCommand`, and the reference in `docs/configuration.md`.
|
||||
After merging, `resolveBuildSections` decides which section describes the builds: `builds` or the legacy `branches`, never both. With no real build definition (`builds.maxConcurrent` is not one, `dropNonDefinitionBuilds` already drops it) the legacy path runs and `branches.default` is merged into every other branch entry; otherwise `branches` is dropped with a warning and `mergeBuildDefaults` applies `builds.default` as the base of every other definition — its settings only, never its `trigger` block (`TRIGGER_KEYS`, a single key so that a selector added to `TriggerConfig` later is non-inheritable by construction). `checkTriggerBlocks` refuses a definition still writing `onPush`/`atTimes`/`branches`/`activeWithin` flat, per file and scoped like the version check. Deciding this on the merged map is deliberate: a build defined on a branch and unknown to the host still inherits the host's `builds.default`, sandbox policy included, which is what keeps the pinned keys effective for it. The result is bound to the `WerkatorConfig` data classes (`config/WerkatorConfig.kt`), which define the schema and all defaults; `WerkatorConfig.buildSettings(branch, build)` is the single answer to "what does this build run".
|
||||
|
||||
Three places must stay in sync when config keys change: the `WerkatorConfig` data classes, the commented templates generated by `InitCommand`, and the reference in `docs/configuration.md`.
|
||||
|
||||
## Git Access
|
||||
|
||||
@@ -59,16 +61,16 @@ Three places must stay in sync when config keys change: the `GitTallyConfig` dat
|
||||
|
||||
## Build Execution
|
||||
|
||||
`BuildExecutor` runs builds asynchronously: up to `executor.maxConcurrent` branches concurrently (default 1), but never more than one build per branch at a time. Each branch builds in its own reusable git worktree at `.git/gittally/worktrees/<branchKey>` (`BranchWorkspaces`), checked out detached at the requested commit — the primary checkout is never used for builds. Status transitions are persisted via `BuildResultRepository` (JSON file under `.git/gittally/`), published to Gitea non-fatally, and emitted as `BuildStatusChangedEvent`s. Every run belongs to a named build definition (job, ADR 0007): the YAML `builds` section defines triggers (`onPush`, `atTimes`), branch selectors (`branches` globs, `activeWithin`), and build-setting overrides applied last over the merged branch config; the implicit `default` build (`onPush`, all branches) preserves the job-less behavior. Definitions are part of the branch layer — a branch may add and override its own, and they apply to that branch alone (its selectors are evaluated for it only) — while `executor.maxConcurrent` stays pinned. `BuildResult.build` records the job; restart, retry, and startup recovery re-run by that name, resolving settings from the *current* config. `BuildResult.name` — the pool, `<branch>@<build>` for non-default builds — keys everything display- and retention-side (repository grouping via `latestPerName`, retention pools, branches-view rows, permanent latest-green links), while `BuildResult.branch` keys everything git-side: origin lookups, gone-from-origin pruning, worktrees (every build runs in its branch's worktree, serialized per branch), and Gitea links/statuses. `branches.*.autoBuild` survives as a deprecated alias for a scheduled default-pool rebuild. Cancellation addresses a build by artifact key and terminates the whole process tree. Future code (watcher, server, UI) must not assume a single running build.
|
||||
`BuildExecutor` runs builds asynchronously: up to `executor.maxConcurrent` branches concurrently (default 1), but never more than one build per branch at a time. Each branch builds in its own reusable git worktree at `.git/werkator/worktrees/<branchKey>` (`BranchWorkspaces`), checked out detached at the requested commit — the primary checkout is never used for builds. Status transitions are persisted via `BuildResultRepository` (JSON file under `.git/werkator/`), published to Gitea non-fatally, and emitted as `BuildStatusChangedEvent`s. Every run belongs to a named build definition (job, ADR 0007): the YAML `builds` section defines triggers (`onPush`, `atTimes`), branch selectors (`branches` globs, `activeWithin`), and build-setting overrides applied last over the merged branch config; the implicit `default` build (`onPush`, all branches) preserves the job-less behavior. Definitions are part of the branch layer — a branch may add and override its own, and they apply to that branch alone (its selectors are evaluated for it only) — while `executor.maxConcurrent` stays pinned. `BuildResult.build` records the job; restart, retry, and startup recovery re-run by that name, resolving settings from the *current* config. `BuildResult.name` — the pool, `<branch>@<build>` for non-default builds — keys everything display- and retention-side (repository grouping via `latestPerName`, retention pools, branches-view rows, permanent latest-green links), while `BuildResult.branch` keys everything git-side: origin lookups, gone-from-origin pruning, worktrees (every build runs in its branch's worktree, serialized per branch), and Gitea links/statuses. `branches.*.autoBuild` survives as a deprecated alias for a scheduled default-pool rebuild. Cancellation addresses a build by artifact key and terminates the whole process tree. Future code (watcher, server, UI) must not assume a single running build.
|
||||
|
||||
On context close (e.g. systemd SIGTERM), a `ContextClosedEvent` listener in `BuildExecutor` terminates the process trees of all executing builds and waits (bounded) until their results are persisted as INTERRUPTED — a shutdown is never recorded as FAILED. Builds still queued stay PENDING and start no process. Both are re-enqueued by the watcher's startup recovery; INTERRUPTED therefore publishes as Gitea state `pending`, not `failure` (`GiteaStateMapping`).
|
||||
|
||||
The runtime is selected per branch behind the `BuildRunner` interface: `DispatchingBuildRunner` (`@Primary`) routes to native `ProcessBuildRunner` (the default) or to `DockerBuildRunner` when `branches.<name>.docker.enabled`. The Docker runner shells out to the `docker` CLI (no SDK): it (re)builds the configured image when the Dockerfile inputs changed (tracked via the `org.gittally.build-inputs-sha256` image label), maintains a per-repo Gradle cache volume, mounts the worktree and the Docker socket into a labelled (`org.hoennig.gittally`) `--rm --init` container, and repairs workspace ownership in-container after each command (under a rootless daemon the container runs as root, which is the host user, and the repair degenerates to `0:0`). Git works inside the container: the primary `.git` is mounted read-only with `.git/gittally/` masked by an empty tmpfs (credential isolation) and the worktree's admin dir mounted read-write (`gitMetadataMounts`). The returned `Process` is the attached `docker run` client, so log streaming and termination work exactly like native builds.
|
||||
The runtime is selected per branch behind the `BuildRunner` interface: `DispatchingBuildRunner` (`@Primary`) routes to native `ProcessBuildRunner` (the default) or to `DockerBuildRunner` when `branches.<name>.docker.enabled`. The Docker runner shells out to the `docker` CLI (no SDK): it (re)builds the configured image when the Dockerfile inputs changed (tracked via the `org.werkator.build-inputs-sha256` image label), maintains a per-repo Gradle cache volume, mounts the worktree and the Docker socket into a labelled (`org.hoennig.werkator`) `--rm --init` container, and repairs workspace ownership in-container after each command (under a rootless daemon the container runs as root, which is the host user, and the repair degenerates to `0:0`). Git works inside the container: the primary `.git` is mounted read-only with `.git/werkator/` masked by an empty tmpfs (credential isolation) and the worktree's admin dir mounted read-write (`gitMetadataMounts`). The returned `Process` is the attached `docker run` client, so log streaming and termination work exactly like native builds.
|
||||
|
||||
## Watcher
|
||||
|
||||
`Watcher` replaces the legacy blocking main loop with a non-blocking fixed-delay poll cycle: fetch origin, enqueue due branches (changed local, recent new origin, due auto-build slots) via `BuildExecutor`, then prune results, artifacts, and stale worktrees. Branches whose build has `requirePullRequest` are enqueued only while their head commit matches a pull-request head, detected without an API token by listing `refs/pull/*/head` via `git ls-remote` (lazily, at most once per poll cycle); manual `build` commands bypass this gate, and `watcher.pullRequestGate: false` disables it globally for plain-git origins without pull-request refs. Which builds are due is decided per branch from that branch's own definitions (`definitionsFor`): the primary config with the branch's committed `.gittally.yml` merged on top, cached per branch by its head commit *and* the primary config it was merged with, so the `git show` runs only when the branch moved while an edited machine or project config still takes effect on the next poll, and falling back to the primary definitions when that config is unreadable. Nothing is scheduled until `Watcher.start()` is called explicitly (server/watch mode) — CLI commands and tests never start the loop. "Already built" is tracked via the result repository, not by moving local branch refs.
|
||||
After the enqueue decision — and only after it, because a local ref lagging behind origin *is* the change signal — the cycle fast-forwards the primary checkout's local branch refs to their origin counterparts (`watcher.fastForwardLocalRefs`, `GitService.fastForwardLocalBranches`), so build tools reading the shared `.git` from a worktree see the refs they expect; diverged or ahead branches are never touched. Auto-build slot state lives in `.git/gittally/auto-builds.json`; watcher health is exposed via `Watcher.state()`.
|
||||
`Watcher` replaces the legacy blocking main loop with a non-blocking fixed-delay poll cycle: fetch origin, enqueue due branches (changed local, recent new origin, due auto-build slots) via `BuildExecutor`, then prune results, artifacts, and stale worktrees. Branches whose build has `requirePullRequest` are enqueued only while their head commit matches a pull-request head, detected without an API token by listing `refs/pull/*/head` via `git ls-remote` (lazily, at most once per poll cycle); manual `build` commands bypass this gate, and `watcher.pullRequestGate: false` disables it globally for plain-git origins without pull-request refs. Which builds are due is decided per branch from that branch's own definitions (`definitionsFor`): the primary config with the branch's committed `.werkator.yml` merged on top, cached per branch by its head commit *and* the primary config it was merged with, so the `git show` runs only when the branch moved while an edited machine or project config still takes effect on the next poll, and falling back to the primary definitions when that config is unreadable. Nothing is scheduled until `Watcher.start()` is called explicitly (server/watch mode) — CLI commands and tests never start the loop. "Already built" is tracked via the result repository, not by moving local branch refs.
|
||||
After the enqueue decision — and only after it, because a local ref lagging behind origin *is* the change signal — the cycle fast-forwards the primary checkout's local branch refs to their origin counterparts (`watcher.fastForwardLocalRefs`, `GitService.fastForwardLocalBranches`), so build tools reading the shared `.git` from a worktree see the refs they expect; diverged or ahead branches are never touched. Auto-build slot state lives in `.git/werkator/auto-builds.json`; watcher health is exposed via `Watcher.state()`.
|
||||
|
||||
## System Metrics
|
||||
|
||||
|
||||
@@ -1,9 +1,9 @@
|
||||
---
|
||||
name: writing-tests
|
||||
description: GitTally testing conventions — Kotest FunSpec spec structure, MockK matchers, and the two patterns for mocking beans in Spring slice tests (springmockk @MockkBean or @TestConfiguration). Use when writing, extending, or refactoring tests.
|
||||
description: Werkator testing conventions — Kotest FunSpec spec structure, MockK matchers, and the two patterns for mocking beans in Spring slice tests (springmockk @MockkBean or @TestConfiguration). Use when writing, extending, or refactoring tests.
|
||||
---
|
||||
|
||||
# Writing Tests for GitTally
|
||||
# Writing Tests for Werkator
|
||||
|
||||
Tests use **Kotest `FunSpec`** style. `SpringExtension` is registered globally in `io.kotest.provided.ProjectConfig` — do not add it per-spec.
|
||||
|
||||
@@ -23,7 +23,7 @@ Tests mirror the production package structure under `src/test/kotlin`.
|
||||
Run a single test class instead of the full suite while iterating:
|
||||
|
||||
```bash
|
||||
./gradlew test --tests "de.hoennig.gittally.ApplicationContextTest"
|
||||
./gradlew test --tests "de.hoennig.werkator.ApplicationContextTest"
|
||||
```
|
||||
|
||||
## Mocking in Spring Slice Tests
|
||||
|
||||
+5
-2
@@ -12,7 +12,7 @@
|
||||
|
||||
# Package Files #
|
||||
*.jar
|
||||
# ... but builds in fresh checkouts (e.g. GitTally worktrees) need the wrapper
|
||||
# ... but builds in fresh checkouts (e.g. Werkator worktrees) need the wrapper
|
||||
!gradle/wrapper/gradle-wrapper.jar
|
||||
*.war
|
||||
*.nar
|
||||
@@ -30,4 +30,7 @@ replay_pid*
|
||||
|
||||
# Gradle
|
||||
.gradle/
|
||||
/build/
|
||||
/build/
|
||||
|
||||
# Other
|
||||
/.local/
|
||||
|
||||
@@ -1,13 +1,13 @@
|
||||
server:
|
||||
# Public base URL of this GitTally installation — used for all links posted to Gitea.
|
||||
# Public base URL of this Werkator installation — used for all links posted to Gitea.
|
||||
publicBaseUrl: ""
|
||||
|
||||
# Gitea integration for fetching commits and posting build statuses.
|
||||
gitea:
|
||||
baseUrl: https://github.com # base URL of the Gitea instance
|
||||
owner: mhoennig # repository owner (user or organisation) for Gitea API (e.g. status checks)
|
||||
repo: gittally # repository name
|
||||
statusContext: GitTally # label shown on Gitea commit status checks (default: GitTally)
|
||||
repo: werkator # repository name
|
||||
statusContext: werkator # label shown on Gitea commit status checks (default: werkator)
|
||||
|
||||
# Build artifact retention.
|
||||
artifacts:
|
||||
@@ -19,19 +19,20 @@ watcher:
|
||||
# max commit age for new origin branches to be pulled automatically
|
||||
newBranchMaxAge: 5d
|
||||
|
||||
# Per-branch build configuration.
|
||||
# Use "default" as the fallback for all branches not listed explicitly.
|
||||
branches:
|
||||
# Named build definitions. "default" is the base every other one inherits its
|
||||
# settings from — never its trigger.
|
||||
builds:
|
||||
default:
|
||||
# When this build runs and for which branches. The only part a build does
|
||||
# NOT inherit from the default — everything below it does.
|
||||
trigger:
|
||||
onPush: true # build every new commit of the selected branches
|
||||
# run before each build
|
||||
cleanCommand: rm -rf build
|
||||
# shell command for each build
|
||||
# shell command for each build
|
||||
buildCommand: ./gradlew --console=plain --no-daemon test
|
||||
# directories copied as build artifacts
|
||||
artifactDirs:
|
||||
artifactDirs:
|
||||
- build/reports
|
||||
stdoutLog: build.stdout.log # filename for captured stdout
|
||||
stderrLog: build.stderr.log # filename for captured stderr
|
||||
autoBuild:
|
||||
enabled: false # whether to rebuild on schedule
|
||||
times: ["01:00"] # UTC times HH:MM for scheduled builds
|
||||
@@ -1,4 +1,4 @@
|
||||
# GitTally — Agent Instructions
|
||||
# Werkator — Agent Instructions
|
||||
|
||||
This file holds the shared, tool-agnostic instructions for all AI coding agents.
|
||||
Claude Code imports it from `CLAUDE.md` via `@AGENTS.md`; Claude-Code-specific instructions belong in `CLAUDE.md`, everything else here.
|
||||
@@ -10,40 +10,40 @@ Detailed guides live as Agent Skills under `.claude/skills/` ([SKILL.md format](
|
||||
./gradlew build # compile + ktlintCheck + test
|
||||
./gradlew ktlintFormat # auto-format before committing
|
||||
./gradlew test # run all tests (can be slow, prefer single test)
|
||||
./gradlew test --tests "de.hoennig.gittally.ApplicationContextTest" # example for running a single test class
|
||||
./gradlew test --tests "de.hoennig.werkator.ApplicationContextTest" # example for running a single test class
|
||||
```
|
||||
|
||||
Run the JAR directly:
|
||||
|
||||
```bash
|
||||
java -jar build/libs/gittally.jar --help
|
||||
java -jar build/libs/gittally.jar init
|
||||
java -jar build/libs/werkator.jar --help
|
||||
java -jar build/libs/werkator.jar init
|
||||
```
|
||||
|
||||
`ktlintFormat` must be run before `build` passes — the formatter is enforced as part of the `check` lifecycle.
|
||||
|
||||
## Architecture Overview
|
||||
|
||||
GitTally is a lightweight, declarative CI/CD build system: git-centric, one instance per repository, builds native or in Docker, statuses reported to Gitea.
|
||||
Werkator is a lightweight, declarative CI/CD build system: git-centric, one instance per repository, builds native or in Docker, statuses reported to Gitea.
|
||||
It is a dual-mode application: **CLI** (interactive, status, config) and **Server** (HTTP, persistent web UI + JSON API).
|
||||
IMPORTANT: Before designing or modifying code in any production package, load the [architecture skill](.claude/skills/architecture/SKILL.md) — it holds the subsystem details (CLI wiring, server mode, web UI, config system, git access, build execution, watcher, metrics).
|
||||
|
||||
### Package Structure
|
||||
|
||||
All production code lives under `de.hoennig.gittally`, with sub-packages `commands` (picocli subcommands), `config` (YAML config loading and schema), `git` (git CLI access), `gitea` (Gitea commit-status API client), `build` (build execution, results, workspaces), `artifacts` (filesystem artifact store), `watcher` (branch polling, auto-builds, startup recovery), `metrics` (system resource sampling and aggregation), and `server` (JSON API controllers, Thymeleaf UI, artifact serving, control token, watcher and metrics lifecycles). Tests mirror this structure under `src/test/kotlin`.
|
||||
All production code lives under `de.hoennig.werkator`, with sub-packages `commands` (picocli subcommands), `config` (YAML config loading and schema), `git` (git CLI access), `gitea` (Gitea commit-status API client), `build` (build execution, results, workspaces), `artifacts` (filesystem artifact store), `watcher` (branch polling, auto-builds, startup recovery), `metrics` (system resource sampling and aggregation), and `server` (JSON API controllers, Thymeleaf UI, artifact serving, control token, watcher and metrics lifecycles). Tests mirror this structure under `src/test/kotlin`.
|
||||
|
||||
### Hard Invariants
|
||||
|
||||
- `exitProcess` is called only from `main()` — never inside `CliRunner.run()`; this keeps the Spring context alive during tests.
|
||||
- Nothing is scheduled during CLI runs or tests: the watcher poll loop and metrics sampling start only via an explicit `start()` in the `server` profile.
|
||||
- Builds run detached in worktrees under `.git/gittally/worktrees/<branchKey>`; the primary checkout is never used for builds; never assume a single running build.
|
||||
- When config keys change, three places must stay in sync: the `GitTallyConfig` data classes, the `InitCommand` templates, and `docs/configuration.md`.
|
||||
- Every config file may declare `gitTally.version.since`/`below` (the GitTally it is written for, never a format version — no API is involved). `since` is enforced in both directions, using `ConfigVersions.FORMAT_BROKE_IN` for "file predates a breaking change"; `below` only warns. A violation aborts the start for the machine and project config, but fails only that branch's builds for a branch config.
|
||||
- A branch describes its own CI: its committed `.gittally.yml` is the branch layer (`ConfigLoader.loadWithBranchLayer`, used by the watcher per origin branch and by `loadForWorktree` at build time) and takes precedence over `.git`/project — including the whole `builds` section, so a new configuration can be tried out on a branch without affecting other branches. Only the pinned set is stripped from that layer: secrets (`git`), host/repository sections (`server`, `gitea`, `executor`, `watcher`), the docker sandbox policy (`docker.enabled`, `docker.network`), and the trust gate (`requirePullRequest`). A branch must never reach credentials, disable its container, change its network, raise global concurrency, or bypass its own pull-request gate; a branch's definitions apply to that branch alone.
|
||||
- Builds run detached in worktrees under `.git/werkator/worktrees/<branchKey>`; the primary checkout is never used for builds; never assume a single running build.
|
||||
- When config keys change, three places must stay in sync: the `WerkatorConfig` data classes, the `InitCommand` templates, and `docs/configuration.md`.
|
||||
- Every config file may declare `werkator.version.since`/`below` (the Werkator it is written for, never a format version — no API is involved). `since` is enforced in both directions, using `ConfigVersions.FORMAT_BROKE_IN` for "file predates a breaking change"; `below` only warns. A violation aborts the start for the machine and project config, but fails only that branch's builds for a branch config.
|
||||
- A branch describes its own CI: its committed `.werkator.yml` is the branch layer (`ConfigLoader.loadWithBranchLayer`, used by the watcher per origin branch and by `loadForWorktree` at build time) and takes precedence over `.git`/project — including the whole `builds` section, so a new configuration can be tried out on a branch without affecting other branches. Only the pinned set is stripped from that layer: secrets (`git`), host/repository sections (`server`, `gitea`, `executor`, `watcher`), the docker sandbox policy (`docker.enabled`, `docker.network`), and the trust gate (`requirePullRequest`). A branch must never reach credentials, disable its container, change its network, raise global concurrency, or bypass its own pull-request gate; a branch's definitions apply to that branch alone.
|
||||
- A build definition carries the complete description of its build, split in two: the `trigger` block (`onPush`, `atTimes`, `branches`, `activeWithin`) says when and for which branches it runs, everything else what it does. `builds.default` is the base every other definition inherits its settings — never its `trigger` — from. The split is structural so that a selector added to `TriggerConfig` later is non-inheritable by construction; writing a trigger key flat is refused, never ignored, because ignoring it leaves a build that silently stops running. A `!` prefix in `trigger.branches` excludes and always wins.
|
||||
- The inheritance is applied after all layers are merged: that order is what makes a build a branch invents inherit the host's sandbox policy instead of the data-class default, so the pinning also holds for a build the host has never heard of. Pinned are `requirePullRequest`, `statusContext`, `docker.enabled`, and `docker.network`.
|
||||
- `builds` or the legacy `branches`, never both: `branches` is read only while the merged config defines no build at all (`builds.maxConcurrent` is not one), and ignored with a warning as soon as one exists. The section is deprecated and goes away once the repositories have migrated; then `ConfigVersions.FORMAT_BROKE_IN` gets set and a leftover `branches:` key must be rejected by name — the version check alone cannot catch a file that declares no version.
|
||||
- Web UI: server-rendered Thymeleaf plus one hand-written `static/gittally.js` — no SPA framework, no frontend build pipeline; every fetch has a timeout and an explicit error badge; `UiFormats` and `gittally.js` must produce identical display formats.
|
||||
- Web UI: server-rendered Thymeleaf plus one hand-written `static/werkator.js` — no SPA framework, no frontend build pipeline; every fetch has a timeout and an explicit error badge; `UiFormats` and `werkator.js` must produce identical display formats.
|
||||
- Git and Docker access shells out to the CLIs (`GitCommandRunner`, `docker`) — no JGit, no Docker SDK.
|
||||
|
||||
## Testing
|
||||
@@ -61,11 +61,11 @@ Keep sentences short.
|
||||
|
||||
## Documentation
|
||||
|
||||
- `docs/GitTally-Konzept.md` — product concept and target architecture (in German): git-centric CI, builds in Docker, one instance per repository, status reported back to Gitea.
|
||||
- `docs/configuration.md` — configuration reference; keep in sync with `GitTallyConfig` and the `init` templates.
|
||||
- `docs/Werkator-Konzept.md` — product concept and target architecture (in German): git-centric CI, builds in Docker, one instance per repository, status reported back to Gitea.
|
||||
- `docs/configuration.md` — configuration reference; keep in sync with `WerkatorConfig` and the `init` templates.
|
||||
- `docs/bootstrapping.md` — how `init` prepares a repository.
|
||||
- `docs/deployment.md` — running GitTally as a systemd user service behind an existing reverse proxy (`init --systemd` generates the unit).
|
||||
- `docs/migration-from-legacy.md` — legacy env vars → YAML keys mapping and the manual migration steps; `legacy/gitTally` is deprecated.
|
||||
- `docs/deployment.md` — running Werkator as a systemd user service behind an existing reverse proxy (`init --systemd` generates the unit).
|
||||
- `docs/werkator-migrationsplan.md` — renaming a running installation from GitTally to Werkator: what the name fallback covers and what has to be moved by hand.
|
||||
- `docs/plan/` — the step-by-step rewrite plan; `docs/plan/README.md` explains how to execute a step, `docs/plan/00-legacy-analysis.md` summarizes the legacy bash script.
|
||||
- `docs/prs/` — one document per pull request; every PR needs one. IMPORTANT: Before opening or finishing a pull request, load the [pr-doc skill](.claude/skills/pr-doc/SKILL.md) and write the PR-doc.
|
||||
|
||||
|
||||
@@ -1,4 +1,4 @@
|
||||
# GitTally — Claude Code Instructions
|
||||
# Werkator — Claude Code Instructions
|
||||
|
||||
@AGENTS.md
|
||||
|
||||
|
||||
@@ -1,4 +1,4 @@
|
||||
# GitTally
|
||||
# Werkator
|
||||
|
||||
Lightweight, declarative and highly opinionated software build system (CI/CD).
|
||||
|
||||
@@ -6,13 +6,7 @@ Lightweight, declarative and highly opinionated software build system (CI/CD).
|
||||
|
||||
- [docs/configuration.md](docs/configuration.md) — configuration reference
|
||||
- [docs/bootstrapping.md](docs/bootstrapping.md) — initializing a repository with `init`
|
||||
- [docs/deployment.md](docs/deployment.md) — running GitTally as a systemd service behind a reverse proxy
|
||||
- [docs/migration-from-legacy.md](docs/migration-from-legacy.md) — migrating from the legacy bash script
|
||||
|
||||
## Legacy Script
|
||||
|
||||
`legacy/gitTally` (bash) is **deprecated** and kept only as a behavioral reference for the rewrite.
|
||||
Do not use it for new installations; see [docs/migration-from-legacy.md](docs/migration-from-legacy.md).
|
||||
- [docs/deployment.md](docs/deployment.md) — running Werkator as a systemd service behind a reverse proxy
|
||||
|
||||
## Developer Setup
|
||||
|
||||
|
||||
+9
-9
@@ -12,7 +12,7 @@ group = "de.hoennig"
|
||||
// bump at least the patch version for every deployment — and only then, not per commit —
|
||||
// so the UI footer (BuildProperties), --version and the release notes identify what is
|
||||
// actually running; a deployment bundles whatever was committed since the last one
|
||||
version = "0.9.21"
|
||||
version = "1.0.0"
|
||||
|
||||
java {
|
||||
toolchain {
|
||||
@@ -69,7 +69,7 @@ springBoot {
|
||||
tasks.bootJar {
|
||||
// version-free jar name, so docs and scripts never contain the version;
|
||||
// the version itself stays available via BuildProperties (UI footer, --version)
|
||||
archiveFileName = "gittally.jar"
|
||||
archiveFileName = "werkator.jar"
|
||||
}
|
||||
|
||||
kotlin {
|
||||
@@ -80,7 +80,7 @@ kotlin {
|
||||
}
|
||||
|
||||
// Self-contained runtime bundle for hosts without a Java runtime (plan step 15, ADR 0006):
|
||||
// a jlink-trimmed JRE plus gittally.jar plus the packaging/gittally launcher, packed as a tarball.
|
||||
// a jlink-trimmed JRE plus werkator.jar plus the packaging/werkator launcher, packed as a tarball.
|
||||
// The JDK module list below was computed from the exploded boot jar via
|
||||
// jdeps -q --ignore-missing-deps --multi-release 21 --print-module-deps \
|
||||
// --class-path 'BOOT-INF/lib/*' BOOT-INF/classes BOOT-INF/lib/*.jar
|
||||
@@ -115,7 +115,7 @@ val runtimeBundle by tasks.registering {
|
||||
|
||||
val jdkHome = javaToolchains.launcherFor(java.toolchain).map { it.metadata.installationPath.asFile }
|
||||
val jarFile = tasks.bootJar.flatMap { it.archiveFile }
|
||||
val launcherFile = layout.projectDirectory.file("packaging/gittally").asFile
|
||||
val launcherFile = layout.projectDirectory.file("packaging/werkator").asFile
|
||||
val stagingDir =
|
||||
layout.buildDirectory
|
||||
.dir("runtime-bundle")
|
||||
@@ -123,7 +123,7 @@ val runtimeBundle by tasks.registering {
|
||||
.asFile
|
||||
val tarballFile =
|
||||
layout.buildDirectory
|
||||
.file("distributions/gittally-runtime-linux-x64.tar.gz")
|
||||
.file("distributions/werkator-runtime-linux-x64.tar.gz")
|
||||
.get()
|
||||
.asFile
|
||||
|
||||
@@ -133,7 +133,7 @@ val runtimeBundle by tasks.registering {
|
||||
outputs.file(tarballFile)
|
||||
|
||||
doLast {
|
||||
val bundleRoot = stagingDir.resolve("gittally")
|
||||
val bundleRoot = stagingDir.resolve("werkator")
|
||||
bundleRoot.deleteRecursively()
|
||||
bundleRoot.parentFile.mkdirs()
|
||||
|
||||
@@ -154,14 +154,14 @@ val runtimeBundle by tasks.registering {
|
||||
val jlinkOutput = jlinkProcess.inputStream.bufferedReader().readText()
|
||||
check(jlinkProcess.waitFor() == 0) { "jlink failed:\n$jlinkOutput" }
|
||||
|
||||
jarFile.get().asFile.copyTo(bundleRoot.resolve("lib/gittally.jar").also { it.parentFile.mkdirs() })
|
||||
val launcher = launcherFile.copyTo(bundleRoot.resolve("bin/gittally").also { it.parentFile.mkdirs() })
|
||||
jarFile.get().asFile.copyTo(bundleRoot.resolve("lib/werkator.jar").also { it.parentFile.mkdirs() })
|
||||
val launcher = launcherFile.copyTo(bundleRoot.resolve("bin/werkator").also { it.parentFile.mkdirs() })
|
||||
check(launcher.setExecutable(true, false)) { "cannot make $launcher executable" }
|
||||
|
||||
tarballFile.parentFile.mkdirs()
|
||||
// system tar preserves the execute bits of jre/bin/* and jre/lib/jspawnhelper
|
||||
val tarProcess =
|
||||
ProcessBuilder("tar", "-czf", tarballFile.absolutePath, "-C", stagingDir.absolutePath, "gittally")
|
||||
ProcessBuilder("tar", "-czf", tarballFile.absolutePath, "-C", stagingDir.absolutePath, "werkator")
|
||||
.redirectErrorStream(true)
|
||||
.start()
|
||||
val tarOutput = tarProcess.inputStream.bufferedReader().readText()
|
||||
|
||||
@@ -1,8 +1,8 @@
|
||||
# GitTally – Konzept und Architekturübersicht
|
||||
# Werkator – Konzept und Architekturübersicht
|
||||
|
||||
## Motivation
|
||||
|
||||
GitTally ist ein bewusst minimalistisches und stark opinionated Continuous-Integration-System (CI), das später um Continuous Delivery (CD) erweitert werden kann.
|
||||
Werkator ist ein bewusst minimalistisches und stark opinionated Continuous-Integration-System (CI), das später um Continuous Delivery (CD) erweitert werden kann.
|
||||
|
||||
Ziel ist es, die Komplexität klassischer CI-Systeme wie Jenkins erheblich zu reduzieren und stattdessen einen einfachen, nachvollziehbaren und git-zentrierten Ansatz zu verfolgen.
|
||||
|
||||
@@ -119,15 +119,15 @@ flowchart LR
|
||||
|
||||
### Commit-basierte Builds
|
||||
|
||||
GitTally baut immer einen konkreten Commit und niemals nur einen Branchnamen.
|
||||
Werkator baut immer einen konkreten Commit und niemals nur einen Branchnamen.
|
||||
Buildergebnisse werden intern trotzdem pro Branch geführt: derselbe Commit auf zwei Branches ergibt zwei getrennte Builds mit eigenem Status, eigenen Artefakten und eigenem Worktree.
|
||||
Das ist gewollt, weil Buildläufe den Branchnamen einbeziehen können (Umgebungsvariable `branch`).
|
||||
In Gitea hängt der Commit-Status dagegen am Commit-SHA: zeigen zwei Branches auf denselben Commit, überschreiben sich ihre Statusmeldungen gegenseitig (der zuletzt gemeldete gewinnt).
|
||||
Falls das je stört, kann der Branchname später in den Status-Context aufgenommen werden (z. B. `GitTally/main`), sodass ein Commit mehrere unabhängige Statuszeilen bekommt.
|
||||
Falls das je stört, kann der Branchname später in den Status-Context aufgenommen werden (z. B. `werkator/main`), sodass ein Commit mehrere unabhängige Statuszeilen bekommt.
|
||||
|
||||
### Worktree pro Branch
|
||||
|
||||
Jeder Branch erhält einen eigenen, wiederverwendeten Worktree unter `.git/gittally/worktrees/<branchKey>`.
|
||||
Jeder Branch erhält einen eigenen, wiederverwendeten Worktree unter `.git/werkator/worktrees/<branchKey>`.
|
||||
Der Branch-Key ist der dateisystem-sicher bereinigte Branchname plus 12 Zeichen SHA-256 des Originalnamens (z. B. `main-0d6e4079e367`).
|
||||
Der Hash schützt nur vor Kollisionen durch die Bereinigung (`feature/x` vs. `feature_x`); der Commit ist bewusst nicht Teil des Keys, damit das Verzeichnis über alle Builds des Branches stabil bleibt.
|
||||
Der zu bauende Commit wird darin detached ausgecheckt.
|
||||
@@ -145,8 +145,8 @@ Ob ein neuer Commit den laufenden Build seines Branches stattdessen abbrechen so
|
||||
|
||||
1. Eingebaute Defaults
|
||||
2. Globale Server-Konfiguration
|
||||
3. Repository-Installation (.git/gittally/.gittally.yml)
|
||||
4. Projektkonfiguration (.gittally.yml)
|
||||
3. Repository-Installation (.git/werkator/.werkator.yml)
|
||||
4. Projektkonfiguration (.werkator.yml)
|
||||
5. Branchprofile
|
||||
|
||||
## Bootstrapping
|
||||
@@ -156,18 +156,18 @@ Ob ein neuer Commit den laufenden Build seines Branches stattdessen abbrechen so
|
||||
- Java Runtime
|
||||
- Git Repository
|
||||
- Ausgecheckter Workspace
|
||||
- GitTally JAR
|
||||
- Werkator JAR
|
||||
|
||||
### Initialisierung
|
||||
|
||||
```bash
|
||||
java -jar build/libs/gittally.jar init
|
||||
java -jar build/libs/werkator.jar init
|
||||
```
|
||||
|
||||
### Serverstart
|
||||
|
||||
```bash
|
||||
java -jar build/libs/gittally.jar server
|
||||
java -jar build/libs/werkator.jar server
|
||||
```
|
||||
|
||||
Für den Dauerbetrieb als systemd-User-Service siehe [deployment.md](deployment.md) (`init --systemd`).
|
||||
@@ -175,13 +175,13 @@ Für den Dauerbetrieb als systemd-User-Service siehe [deployment.md](deployment.
|
||||
### Konfigurationsanzeige
|
||||
|
||||
```bash
|
||||
java -jar build/libs/gittally.jar config:print
|
||||
java -jar build/libs/gittally.jar config:print --full
|
||||
java -jar build/libs/werkator.jar config:print
|
||||
java -jar build/libs/werkator.jar config:print --full
|
||||
```
|
||||
|
||||
## Erweiterungen
|
||||
|
||||
- Continuous Delivery (CD; das Deployment von GitTally selbst ist in [deployment.md](deployment.md) beschrieben)
|
||||
- Continuous Delivery (CD; das Deployment von Werkator selbst ist in [deployment.md](deployment.md) beschrieben)
|
||||
- SQLite statt Dateisystem
|
||||
- Mehrere BuildWorker
|
||||
- Multi-Repository-Verwaltung
|
||||
@@ -10,7 +10,7 @@
|
||||
|
||||
## Context and Problem Statement
|
||||
|
||||
GitTally is a greenfield Kotlin/Spring Boot project.
|
||||
Werkator is a greenfield Kotlin/Spring Boot project.
|
||||
A test framework must be chosen before writing any tests.
|
||||
|
||||
The framework shapes how tests are structured, how readable they are, and how well they integrate with the Spring Boot test slice infrastructure.
|
||||
|
||||
@@ -10,7 +10,7 @@
|
||||
|
||||
## Context and Problem Statement
|
||||
|
||||
GitTally is a greenfield Kotlin/Spring Boot project.
|
||||
Werkator is a greenfield Kotlin/Spring Boot project.
|
||||
A Gradle version must be chosen for the initial setup.
|
||||
|
||||
[Gradle 9](https://docs.gradle.org/9.3.0/release-notes.html) (currently 9.5.1) is now stable and available.
|
||||
|
||||
@@ -10,7 +10,7 @@
|
||||
|
||||
## Context and Problem Statement
|
||||
|
||||
GitTally is a greenfield Kotlin/Spring Boot project.
|
||||
Werkator is a greenfield Kotlin/Spring Boot project.
|
||||
A Spring Boot version must be chosen for the initial setup.
|
||||
|
||||
The choice is constrained by the support lifecycle: as of June 2026,
|
||||
|
||||
@@ -10,7 +10,7 @@
|
||||
|
||||
## Context and Problem Statement
|
||||
|
||||
The rewrite of `legacy/gitTally` (bash) as a Kotlin/Spring application (see `docs/plan/`) required several cross-cutting architecture decisions.
|
||||
The rewrite of `legacy/werkator` (bash) as a Kotlin/Spring application (see `docs/plan/`) required several cross-cutting architecture decisions.
|
||||
They were proposed in `docs/plan/README.md`, validated step by step during implementation, and are summarized here as one record.
|
||||
|
||||
### Technical Background
|
||||
@@ -26,7 +26,7 @@ Its two structural defects — build status not observable during a build, and a
|
||||
|
||||
### Persistence: JSON files behind `BuildResultRepository`
|
||||
|
||||
Build results are persisted as a JSON file under `.git/gittally/`, accessed only through the `BuildResultRepository` interface.
|
||||
Build results are persisted as a JSON file under `.git/werkator/`, accessed only through the `BuildResultRepository` interface.
|
||||
|
||||
#### Advantages
|
||||
|
||||
@@ -54,7 +54,7 @@ Pages render the full state server-side; one hand-written JavaScript file polls
|
||||
|
||||
### Deployment: no managed nginx, systemd user unit instead
|
||||
|
||||
nginx/Let's Encrypt container management was not ported; `init --systemd` generates a user unit running `java -jar gittally.jar server`, and `docs/deployment.md` documents the reverse-proxy setup with the host's certbot.
|
||||
nginx/Let's Encrypt container management was not ported; `init --systemd` generates a user unit running `java -jar werkator.jar server`, and `docs/deployment.md` documents the reverse-proxy setup with the host's certbot.
|
||||
|
||||
#### Advantages
|
||||
|
||||
@@ -64,7 +64,7 @@ nginx/Let's Encrypt container management was not ported; `init --systemd` genera
|
||||
|
||||
#### Disadvantages
|
||||
|
||||
- HTTPS setup is a manual, host-specific step outside GitTally's control.
|
||||
- HTTPS setup is a manual, host-specific step outside Werkator's control.
|
||||
|
||||
## Decision Outcome
|
||||
|
||||
|
||||
@@ -6,7 +6,7 @@
|
||||
- rejected: -
|
||||
- superseded: -
|
||||
|
||||
**Decision [accepted]:** GitTally optionally manages an nginx+certbot Docker container for hosts without a usable reverse proxy — revises the "no managed nginx" part of ADR 0004; deployment behind an existing reverse proxy stays the default.
|
||||
**Decision [accepted]:** Werkator optionally manages an nginx+certbot Docker container for hosts without a usable reverse proxy — revises the "no managed nginx" part of ADR 0004; deployment behind an existing reverse proxy stays the default.
|
||||
|
||||
## Context and Problem Statement
|
||||
|
||||
@@ -15,22 +15,22 @@ That decision was carried over from the rewrite plan without validating it again
|
||||
|
||||
### Technical Background
|
||||
|
||||
GitTally must run on Hostsharing managed container environments.
|
||||
These hosts provide Docker but no root access and no host web server that GitTally could sit behind.
|
||||
Without the managed nginx container, GitTally cannot be served over HTTPS there at all.
|
||||
Werkator must run on Hostsharing managed container environments.
|
||||
These hosts provide Docker but no root access and no host web server that Werkator could sit behind.
|
||||
Without the managed nginx container, Werkator cannot be served over HTTPS there at all.
|
||||
The legacy script already solved this: it wrote an nginx config, ran an nginx Docker container, and obtained/renewed Let's Encrypt certificates via a certbot container in webroot mode.
|
||||
|
||||
## Considered Options
|
||||
|
||||
* Keep ADR 0004 as is (host reverse proxy only)
|
||||
* Re-add the legacy managed nginx+certbot container as an opt-in feature
|
||||
* External tooling (user-maintained compose stack next to GitTally)
|
||||
* External tooling (user-maintained compose stack next to Werkator)
|
||||
|
||||
### Host reverse proxy only
|
||||
|
||||
#### Advantages
|
||||
|
||||
- No container lifecycle or certificate code in GitTally.
|
||||
- No container lifecycle or certificate code in werkator.
|
||||
|
||||
#### Disadvantages
|
||||
|
||||
@@ -38,7 +38,7 @@ The legacy script already solved this: it wrote an nginx config, ran an nginx Do
|
||||
|
||||
### Opt-in managed nginx+certbot container
|
||||
|
||||
GitTally starts and supervises a labelled nginx container and handles certificate issuance/renewal via certbot, only when explicitly enabled in the config.
|
||||
Werkator starts and supervises a labelled nginx container and handles certificate issuance/renewal via certbot, only when explicitly enabled in the config.
|
||||
|
||||
#### Advantages
|
||||
|
||||
@@ -48,13 +48,13 @@ GitTally starts and supervises a labelled nginx container and handles certificat
|
||||
|
||||
#### Disadvantages
|
||||
|
||||
- Re-adds container lifecycle and certificate renewal complexity to GitTally.
|
||||
- Re-adds container lifecycle and certificate renewal complexity to werkator.
|
||||
|
||||
### External compose stack
|
||||
|
||||
#### Advantages
|
||||
|
||||
- Keeps GitTally itself simple.
|
||||
- Keeps Werkator itself simple.
|
||||
|
||||
#### Disadvantages
|
||||
|
||||
|
||||
@@ -6,30 +6,30 @@
|
||||
- rejected: -
|
||||
- superseded: -
|
||||
|
||||
**Decision [accepted]:** GitTally is distributed for hosts without a Java runtime as a self-contained runtime bundle — a jlink-trimmed JRE plus `gittally.jar` plus a launcher script in one tarball, built by `./gradlew runtimeBundle`.
|
||||
The JAR stays the primary artifact; a GraalVM native image and a containerized GitTally runtime were rejected.
|
||||
**Decision [accepted]:** Werkator is distributed for hosts without a Java runtime as a self-contained runtime bundle — a jlink-trimmed JRE plus `werkator.jar` plus a launcher script in one tarball, built by `./gradlew runtimeBundle`.
|
||||
The JAR stays the primary artifact; a GraalVM native image and a containerized Werkator runtime were rejected.
|
||||
|
||||
## Context and Problem Statement
|
||||
|
||||
GitTally must run on Hostsharing container servers (the primary target, see ADR 0005).
|
||||
Werkator must run on Hostsharing container servers (the primary target, see ADR 0005).
|
||||
These hosts provide git, Docker, make, and systemd user sessions, but no Java runtime, and nothing may be installed system-wide.
|
||||
`docs/bootstrapping.md` sketched a containerized GitTally runtime as the future answer; that sketch was never validated against the operational details.
|
||||
`docs/bootstrapping.md` sketched a containerized Werkator runtime as the future answer; that sketch was never validated against the operational details.
|
||||
|
||||
## Considered Options
|
||||
|
||||
* jlink runtime bundle (trimmed JRE + jar + launcher, one tarball)
|
||||
* GraalVM native image (single executable)
|
||||
* Containerized GitTally runtime (the original `docs/bootstrapping.md` sketch)
|
||||
* Containerized Werkator runtime (the original `docs/bootstrapping.md` sketch)
|
||||
|
||||
### jlink Runtime Bundle
|
||||
|
||||
A `jlink`-generated JRE with the pinned module list, the boot jar, and a `bin/gittally` launcher script, packed as `gittally-runtime-linux-x64.tar.gz` (~66 MB) and unpacked to `~/opt/gittally/` on the target host.
|
||||
A `jlink`-generated JRE with the pinned module list, the boot jar, and a `bin/werkator` launcher script, packed as `werkator-runtime-linux-x64.tar.gz` (~66 MB) and unpacked to `~/opt/werkator/` on the target host.
|
||||
|
||||
Good:
|
||||
|
||||
- No production-code changes and plain JVM semantics — no new failure modes.
|
||||
- git and docker CLIs are used from the host; build worktree paths stay host paths.
|
||||
- `init --systemd` works unchanged: `java.home` and the running-jar path resolve into the bundle, so the generated unit points at `<bundle>/jre/bin/java` and `<bundle>/lib/gittally.jar` (verified).
|
||||
- `init --systemd` works unchanged: `java.home` and the running-jar path resolve into the bundle, so the generated unit points at `<bundle>/jre/bin/java` and `<bundle>/lib/werkator.jar` (verified).
|
||||
- Every JDK 21 ships jlink — no new build-toolchain requirement.
|
||||
|
||||
Bad:
|
||||
@@ -44,12 +44,12 @@ Bad:
|
||||
|
||||
### GraalVM Native Image
|
||||
|
||||
Rejected because Spring AOT evaluates bean conditions at build time, and GitTally's dual-mode wiring cannot be represented in a single AOT arrangement:
|
||||
Rejected because Spring AOT evaluates bean conditions at build time, and Werkator's dual-mode wiring cannot be represented in a single AOT arrangement:
|
||||
the CLI context runs without web and with `@Profile("!server")` `CliRunner`, while the `server` subcommand starts a second `SpringApplication` with `WebApplicationType.SERVLET` and the `server` profile gating the watcher/metrics/nginx lifecycles.
|
||||
Whichever profile and web type the AOT processing fixes, the other mode's beans are missing from the binary.
|
||||
Supporting both would require replacing the profile wiring with runtime guards and collapsing the two context shapes — an invasive rewrite with regression risk for the JVM path, on top of the usual native-image reflection work (Jackson-bound config and persistence classes, picocli).
|
||||
|
||||
### Containerized GitTally Runtime
|
||||
### Containerized Werkator Runtime
|
||||
|
||||
Rejected for operational complexity: the image must bundle git and docker CLIs; the container needs a same-path `$HOME` mount plus a docker-socket mount and uid/gid mapping so that `DockerBuildRunner`'s `--volume $workspace:$workspace` sibling mounts keep working; and the systemd unit must be hand-edited to a `docker run` invocation.
|
||||
This remains the documented fallback if the runtime bundle ever becomes unworkable.
|
||||
|
||||
@@ -11,7 +11,7 @@
|
||||
|
||||
## Context and Problem Statement
|
||||
|
||||
GitTally's configuration is branch-centric: `branches.<name>` holds the build settings, and the nightly schedule (`autoBuild`) hangs off the branch.
|
||||
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.
|
||||
|
||||
@@ -73,7 +73,7 @@ A build definition has:
|
||||
|
||||
Semantics:
|
||||
|
||||
- **Merge order** for the effective settings of one build on one branch: config defaults → `branches.default` → `branches.<branch>` → the worktree's committed `.gittally.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.
|
||||
- **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.
|
||||
@@ -119,7 +119,7 @@ Follow-up (2026-08-28): mixing the execution key `maxConcurrent` into the `build
|
||||
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 `.gittally.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.
|
||||
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.
|
||||
|
||||
+23
-23
@@ -1,6 +1,6 @@
|
||||
# GitTally Bootstrapping
|
||||
# Werkator Bootstrapping
|
||||
|
||||
Bootstrapping prepares a git repository for use with GitTally.
|
||||
Bootstrapping prepares a git repository for use with werkator.
|
||||
It creates the config files described in [configuration.md](configuration.md).
|
||||
With `init --systemd` it also generates a systemd user unit for running the server permanently, see [deployment.md](deployment.md).
|
||||
|
||||
@@ -14,7 +14,7 @@ Run `init` once per repository, from within a checked-out working tree.
|
||||
|
||||
## Running `init`
|
||||
|
||||
First, in `<gittally-root>`, build the application to generate the executable JAR file:
|
||||
First, in `<werkator-root>`, build the application to generate the executable JAR file:
|
||||
|
||||
```bash
|
||||
./gradlew build
|
||||
@@ -23,21 +23,21 @@ First, in `<gittally-root>`, build the application to generate the executable JA
|
||||
Then run `init` using the generated JAR (not the `-plain.jar`):
|
||||
|
||||
```bash
|
||||
java -jar <gittally-root>/build/libs/gittally.jar init
|
||||
java -jar <werkator-root>/build/libs/werkator.jar init
|
||||
```
|
||||
|
||||
`init` performs the following steps in order:
|
||||
|
||||
### 1. Detect the Repository Root
|
||||
|
||||
GitTally resolves the repository root by running `git rev-parse --show-toplevel`.
|
||||
Werkator resolves the repository root by running `git rev-parse --show-toplevel`.
|
||||
If the current directory is not inside a git repository, `init` exits with an error.
|
||||
|
||||
### 2. Auto-detect Gitea Connection from `origin`
|
||||
|
||||
If `gitea.baseUrl`, `gitea.owner`, and `gitea.repo` are already set in `.gittally.yml`, these values are used.
|
||||
If `gitea.baseUrl`, `gitea.owner`, and `gitea.repo` are already set in `.werkator.yml`, these values are used.
|
||||
|
||||
Otherwise, GitTally inspects the `origin` remote URL and derives the Gitea connection defaults:
|
||||
Otherwise, Werkator inspects the `origin` remote URL and derives the Gitea connection defaults:
|
||||
|
||||
| Origin URL form | Detected values |
|
||||
|--------------------------------------------|----------------------------------------|
|
||||
@@ -52,7 +52,7 @@ The `.git` suffix is stripped from the repo name. The username embedded in HTTPS
|
||||
|
||||
### 3. Create the Repo-Install Config
|
||||
|
||||
Creates `.git/gittally/.gittally.yml` (and its parent directory if needed).
|
||||
Creates `.git/werkator/.werkator.yml` (and its parent directory if needed).
|
||||
This file is **never committed** to the repository and is used for all branches,
|
||||
as long as not overridden by a project config.
|
||||
|
||||
@@ -68,7 +68,7 @@ git:
|
||||
|
||||
### 4. Create the Branch/Project Config
|
||||
|
||||
Creates `.gittally.yml` in the repository root with project-level defaults.
|
||||
Creates `.werkator.yml` in the repository root with project-level defaults.
|
||||
|
||||
If the file already exists, `init` prints a notice and leaves it untouched.
|
||||
|
||||
@@ -84,55 +84,55 @@ gitea:
|
||||
...
|
||||
```
|
||||
|
||||
Then, you have to configure *gitTally* by amending this config file according to [configuration.md](configuration.md).
|
||||
Then, you have to configure *Werkator* by amending this config file according to [configuration.md](configuration.md).
|
||||
|
||||
## Output
|
||||
|
||||
`init` prints one line per action taken:
|
||||
|
||||
```
|
||||
created .git/gittally/.gittally.yml
|
||||
created .gittally.yml
|
||||
created .git/werkator/.werkator.yml
|
||||
created .werkator.yml
|
||||
```
|
||||
|
||||
Or, when files already exist:
|
||||
|
||||
```
|
||||
.git/gittally/.gittally.yml already exists — not overwritten
|
||||
.gittally.yml already exists — not overwritten
|
||||
.git/werkator/.werkator.yml already exists — not overwritten
|
||||
.werkator.yml already exists — not overwritten
|
||||
```
|
||||
|
||||
## Hosts Without a Java Runtime
|
||||
|
||||
GitTally is intended to run on Hostsharing Container Server environments, which provide Docker and git but no Java runtime.
|
||||
Werkator is intended to run on Hostsharing Container Server environments, which provide Docker and git but no Java runtime.
|
||||
For these hosts, `./gradlew runtimeBundle` builds a self-contained runtime bundle (jlink-trimmed JRE + JAR + launcher) — see [deployment.md](deployment.md) and ADR 0006.
|
||||
A containerized GitTally runtime was considered and rejected there.
|
||||
A containerized Werkator runtime was considered and rejected there.
|
||||
|
||||
## Next Steps After `init`
|
||||
|
||||
1. Open `.git/gittally/.gittally.yml` and set `git.token` and `git.account`.
|
||||
2. Review `.gittally.yml` and add/adjust any branch build settings.
|
||||
1. Open `.git/werkator/.werkator.yml` and set `git.token` and `git.account`.
|
||||
2. Review `.werkator.yml` and add/adjust any branch build settings.
|
||||
3. Verify the effective configuration:
|
||||
```bash
|
||||
java -jar build/libs/gittally.jar config:print --full
|
||||
java -jar build/libs/werkator.jar config:print --full
|
||||
```
|
||||
4. Start the server:
|
||||
```bash
|
||||
java -jar build/libs/gittally.jar server
|
||||
java -jar build/libs/werkator.jar server
|
||||
```
|
||||
5. For permanent operation, install the systemd user service described in [deployment.md](deployment.md).
|
||||
|
||||
## Example: Test Server with a Fake Build
|
||||
|
||||
[examples/setup-gittally-testserver.sh](examples/setup-gittally-testserver.sh) starts a GitTally server against a scratch repository with a fake build — the setup used for the manual UI/API smoke tests during development.
|
||||
[examples/setup-werkator-testserver.sh](examples/setup-werkator-testserver.sh) starts a Werkator server against a scratch repository with a fake build — the setup used for the manual UI/API smoke tests during development.
|
||||
It creates a local bare origin plus a `work` clone, commits a slow fake build script (live log output, demo report artifact) with a `pollInterval: 5s` config, and starts the server on port 18980.
|
||||
The origin gets a second branch (`feature/demo`), so the Branches view shows more than one entry.
|
||||
No Gitea, no credentials, no Docker; `INSTALL_DIR`, `SERVER_PORT`, and `BUILD_SECONDS` can be overridden via environment variables.
|
||||
While the server runs, push empty commits from the `work` clone to trigger builds; a commit message containing `[fail]` makes the build fail, and pushing a new branch exercises the new-origin-branch path.
|
||||
|
||||
## Example: Self-Hosting GitTally
|
||||
## Example: Self-Hosting Werkator
|
||||
|
||||
[examples/setup-gittally-selfhost.sh](examples/setup-gittally-selfhost.sh) shows the full sequence as a runnable script: it sets up a GitTally instance that watches and builds GitTally itself.
|
||||
[examples/setup-werkator-selfhost.sh](examples/setup-werkator-selfhost.sh) shows the full sequence as a runnable script: it sets up a Werkator instance that watches and builds Werkator itself.
|
||||
Run it from a working checkout; it builds the JAR, creates a dedicated clone, runs `init`, writes the machine-specific config, and starts the server.
|
||||
`INSTALL_DIR`, `ORIGIN_URL`, `SERVER_PORT`, `GIT_ACCOUNT`, and `GIT_TOKEN` can be overridden via environment variables.
|
||||
The script also demonstrates the kick-start trick: resetting the local ref one commit behind origin makes the very first poll build immediately, instead of waiting for the next push.
|
||||
|
||||
+52
-52
@@ -1,53 +1,53 @@
|
||||
# GitTally Configuration Reference
|
||||
# Werkator Configuration Reference
|
||||
|
||||
GitTally is configured via YAML files. Settings are merged from several sources in order — later layers override earlier ones.
|
||||
Werkator is configured via YAML files. Settings are merged from several sources in order — later layers override earlier ones.
|
||||
|
||||
## Config File Locations
|
||||
|
||||
| Layer | Path | Committed to Git | Purpose |
|
||||
|--------------------------|----------------------------|------------------|----------------------------------------------|
|
||||
| Project config | `.gittally.yml` | Yes | Shared team settings |
|
||||
| Repo installation config | `.git/gittally/.gittally.yml` | No | Machine- or user-specific overrides, secrets |
|
||||
| Branch config | `.gittally.yml` committed on a branch | Yes | That branch's build settings and build definitions |
|
||||
| Project config | `.werkator.yml` | Yes | Shared team settings |
|
||||
| Repo installation config | `.git/werkator/.werkator.yml` | No | Machine- or user-specific overrides, secrets |
|
||||
| Branch config | `.werkator.yml` committed on a branch | Yes | That branch's build settings and build definitions |
|
||||
|
||||
The repo install config (`.git/gittally/.gittally.yml`) wins on any key present in both files. Typically used to set `git.token` and `git.account` without committing them.
|
||||
The repo install config (`.git/werkator/.werkator.yml`) wins on any key present in both files. Typically used to set `git.token` and `git.account` without committing them.
|
||||
|
||||
### Which GitTally a file is written for
|
||||
### Which Werkator a file is written for
|
||||
|
||||
Every configuration file may declare the GitTally it was written for. Without it, a
|
||||
Every configuration file may declare the Werkator it was written for. Without it, a
|
||||
version that renames or drops a key does not fail — it silently ignores what it no longer
|
||||
understands, and the effect shows up as a build that does the wrong thing.
|
||||
|
||||
```yaml
|
||||
gitTally:
|
||||
werkator:
|
||||
version:
|
||||
since: "0.9.16" # enforced: an older GitTally refuses to read this file
|
||||
below: "2.0" # your release marker; GitTally decides how strictly to take it
|
||||
since: "0.9.16" # enforced: an older Werkator refuses to read this file
|
||||
below: "2.0" # your release marker; Werkator decides how strictly to take it
|
||||
```
|
||||
|
||||
There is deliberately **no version of the file format** (no `apiVersion`): no API is
|
||||
involved — GitTally reads its own configuration — and only one configuration generation is
|
||||
involved — Werkator reads its own configuration — and only one configuration generation is
|
||||
ever supported. The declaration exists to make an incompatibility nameable, never to run
|
||||
two parsers.
|
||||
|
||||
`since` is a hard floor and covers both directions:
|
||||
|
||||
- a newer file on an older GitTally is refused instead of being half-understood;
|
||||
- a newer file on an older Werkator is refused instead of being half-understood;
|
||||
- a file written *before* a breaking change and read *after* it is refused as well —
|
||||
GitTally knows in which version its configuration format last broke, so the message can
|
||||
name the change: *"is written for GitTally 1.4.0, but the configuration format changed
|
||||
Werkator knows in which version its configuration format last broke, so the message can
|
||||
name the change: *"is written for Werkator 1.4.0, but the configuration format changed
|
||||
incompatibly in 2.0.0: `builds:` is now `buildSpec:`"*.
|
||||
|
||||
`below` is optional and names the first version this file was **not** released for. The
|
||||
bound is exclusive, so `below: "2.0"` means everything up to 2.0.0. On its own it only
|
||||
warns — a caution marker nobody maintained must never stop a CI. The refusal above comes
|
||||
from GitTally's own knowledge of its breaking changes, not from this value. The intended
|
||||
from Werkator's own knowledge of its breaking changes, not from this value. The intended
|
||||
routine is the one known from IDE plugins: a new version appears, the warning shows up, you
|
||||
try it (on a test host, or in production with a rollback ready), and then raise `below` and
|
||||
commit that.
|
||||
|
||||
A file that declares nothing is read as before, with a hint in the log — a missing line
|
||||
must never stop a server either. `gittally init` writes the running version into the
|
||||
must never stop a server either. `werkator init` writes the running version into the
|
||||
generated config.
|
||||
|
||||
How far a violation reaches depends on the file, following the same rule as everything
|
||||
@@ -58,7 +58,7 @@ branches that are fine.
|
||||
|
||||
### The branch layer: a branch describes its own CI
|
||||
|
||||
The `.gittally.yml` committed on a branch is applied as a third layer on top of the two
|
||||
The `.werkator.yml` committed on a branch is applied as a third layer on top of the two
|
||||
above, giving the precedence **branch > repo install > project**. It takes precedence for
|
||||
everything that describes how this branch is built: the whole `builds` section — its own
|
||||
definitions and its overrides of the definitions from the project config, with
|
||||
@@ -95,7 +95,7 @@ single branch may decide it:
|
||||
configuration does.
|
||||
|
||||
The distinction is documentary.
|
||||
GitTally applies one rule: every pinned key is stripped from the branch layer, and the
|
||||
Werkator applies one rule: every pinned key is stripped from the branch layer, and the
|
||||
value then resolves from whichever remaining layer sets it.
|
||||
The names say where a key is meant to live, not how it is enforced.
|
||||
|
||||
@@ -110,26 +110,26 @@ install/project config only, and only while nothing defines a build at all.
|
||||
## Inspect the Effective Config
|
||||
|
||||
```bash
|
||||
java -jar build/libs/gittally.jar config:print # only explicitly set values
|
||||
java -jar build/libs/gittally.jar config:print --full # all values including defaults
|
||||
java -jar build/libs/werkator.jar config:print # only explicitly set values
|
||||
java -jar build/libs/werkator.jar config:print --full # all values including defaults
|
||||
```
|
||||
|
||||
`git.token` is masked as `***` by default, so the output can safely be shared or pasted.
|
||||
Add `--show-secrets` to print it in clear text.
|
||||
|
||||
## `.gittally.yml`
|
||||
## `.werkator.yml`
|
||||
|
||||
Values shown are the defaults.
|
||||
|
||||
```yaml
|
||||
# The GitTally this file is written for (see the section above).
|
||||
gitTally:
|
||||
# The Werkator this file is written for (see the section above).
|
||||
werkator:
|
||||
version:
|
||||
since: "0.9.18" # enforced: older GitTally refuses this file
|
||||
since: "0.9.18" # enforced: older Werkator refuses this file
|
||||
below: "2.0" # optional release marker; warns, does not block
|
||||
|
||||
server:
|
||||
# Public base URL of this GitTally installation — used for all links posted to Gitea.
|
||||
# Public base URL of this Werkator installation — used for all links posted to Gitea.
|
||||
publicBaseUrl: https://ci.example.org/
|
||||
# HTTP port of the `server` subcommand (default 18080, like legacy)
|
||||
port: 18080
|
||||
@@ -151,10 +151,10 @@ server:
|
||||
httpsPort: 8443
|
||||
# host nginx proxies to; empty = serverName (the container cannot reach localhost)
|
||||
upstreamHost: ""
|
||||
# name of the managed container; empty = gittally-nginx-<repo-name>
|
||||
# name of the managed container; empty = werkator-nginx-<repo-name>
|
||||
containerName: ""
|
||||
# directory for nginx config, certificates, and logs;
|
||||
# empty = $XDG_STATE_HOME (or ~/.local/state) plus /gittally/nginx/<repo-key>
|
||||
# empty = $XDG_STATE_HOME (or ~/.local/state) plus /werkator/nginx/<repo-key>
|
||||
stateDir: ""
|
||||
# e-mail for the Let's Encrypt account; empty registers without one
|
||||
letsencryptEmail: ""
|
||||
@@ -164,14 +164,14 @@ gitea:
|
||||
baseUrl: https://git.example.org # base URL of the Gitea instance
|
||||
owner: my-org # repository owner (user or organisation) for Gitea API (e.g. status checks)
|
||||
repo: my-repo # repository name
|
||||
statusContext: GitTally # label shown on Gitea commit status checks (default: GitTally)
|
||||
statusContext: werkator # label shown on Gitea commit status checks (default: werkator)
|
||||
|
||||
# Build execution settings, enforced for all builds regardless of their trigger
|
||||
# (watcher, UI restart, CLI build/retry).
|
||||
executor:
|
||||
# How many builds may run at the same time.
|
||||
# At most one build per branch runs regardless; each branch builds in its own
|
||||
# git worktree under .git/gittally/worktrees/, never in the primary checkout.
|
||||
# git worktree under .git/werkator/worktrees/, never in the primary checkout.
|
||||
# Changing this value requires a restart.
|
||||
maxConcurrent: 1
|
||||
|
||||
@@ -233,12 +233,12 @@ builds:
|
||||
activeWithin: 24h
|
||||
buildCommand: ./gradlew -PfullPitTest --console=plain --no-daemon piTestFull
|
||||
artifactDirs: [build/reports, build/libs]
|
||||
statusContext: GitTally/pitest
|
||||
statusContext: werkator/pitest
|
||||
|
||||
# Build artifact storage and retention.
|
||||
artifacts:
|
||||
# Root directory for stored build artifacts.
|
||||
# Empty means the platform default: $XDG_STATE_HOME (or ~/.local/state) plus /gittally/artifacts/<repo-key>,
|
||||
# Empty means the platform default: $XDG_STATE_HOME (or ~/.local/state) plus /werkator/artifacts/<repo-key>,
|
||||
# where <repo-key> is the sanitized absolute repository path.
|
||||
# A leading ~/ expands to the home directory; a relative path is resolved against the repository.
|
||||
rootDir: ""
|
||||
@@ -275,24 +275,24 @@ watcher:
|
||||
### Notes on `server.bindAddress`
|
||||
|
||||
The default is `127.0.0.1`.
|
||||
Neither the web UI nor the JSON API authenticates read access — which is intended, so build states and artifacts can be linked from anywhere — so GitTally is meant to sit behind the host's reverse proxy rather than on a public interface.
|
||||
Set `0.0.0.0` only deliberately — for the managed nginx container (which reaches GitTally over the Docker bridge, not over loopback), or when the proxy runs on another host.
|
||||
Installations created before v0.9.9 have `bindAddress: 0.0.0.0` written into their `.gittally.yml` and keep it; the new default only applies where the key is absent or `init` writes a fresh file.
|
||||
Neither the web UI nor the JSON API authenticates read access — which is intended, so build states and artifacts can be linked from anywhere — so Werkator is meant to sit behind the host's reverse proxy rather than on a public interface.
|
||||
Set `0.0.0.0` only deliberately — for the managed nginx container (which reaches Werkator over the Docker bridge, not over loopback), or when the proxy runs on another host.
|
||||
Installations created before v0.9.9 have `bindAddress: 0.0.0.0` written into their `.werkator.yml` and keep it; the new default only applies where the key is absent or `init` writes a fresh file.
|
||||
|
||||
### Notes on `server.nginx`
|
||||
|
||||
With `nginx.enabled`, the `server` subcommand also starts a managed nginx Docker container that serves GitTally over HTTPS (ADR 0005).
|
||||
With `nginx.enabled`, the `server` subcommand also starts a managed nginx Docker container that serves Werkator over HTTPS (ADR 0005).
|
||||
This is meant for hosts that provide Docker but no usable reverse proxy (e.g. Hostsharing managed containers); otherwise prefer the reverse-proxy setup in [deployment.md](deployment.md).
|
||||
Certificates are obtained and renewed via Let's Encrypt (certbot Docker container, webroot mode), so `serverName` must be a public DNS name pointing at the host and `httpPort` must be reachable from the internet as port 80 (or via a port forward).
|
||||
When `server.publicBaseUrl` is empty and `serverName` is set, it defaults to `https://<serverName>/`.
|
||||
All nginx/certificate failures are non-fatal warnings; the plain HTTP server keeps running without the proxy.
|
||||
The container is labelled `org.hoennig.gittally`; stale nginx containers of the repository are removed before each start, and the container is removed on shutdown.
|
||||
The container is labelled `org.hoennig.werkator`; stale nginx containers of the repository are removed before each start, and the container is removed on shutdown.
|
||||
`server.port` must differ from `httpPort` and `httpsPort`.
|
||||
|
||||
### Notes on `builds.<name>.requirePullRequest`
|
||||
|
||||
The gate applies to all watcher-triggered builds (push-triggered and scheduled auto builds).
|
||||
A manual `gittally build <branch>` always builds, regardless of this setting.
|
||||
A manual `werkator build <branch>` always builds, regardless of this setting.
|
||||
|
||||
Detection works without a Gitea API token:
|
||||
the watcher lists `refs/pull/*/head` on origin via `git ls-remote` and builds a branch only when its head commit equals one of those pull-request head commits.
|
||||
@@ -321,7 +321,7 @@ Without that second definition, direct pushes and merges to `main` would never b
|
||||
The `!main` exclusion keeps the default build off it, so a push is built once instead of by both definitions.
|
||||
|
||||
A plain git origin (no Gitea/GitHub) serves no `refs/pull/*/head` at all, so gated branches would never build there.
|
||||
For such origins, disable all gates globally with `watcher.pullRequestGate: false` — typically in the machine-specific `.git/gittally/.gittally.yml`, so the committed configuration keeps the gates for forge-backed environments.
|
||||
For such origins, disable all gates globally with `watcher.pullRequestGate: false` — typically in the machine-specific `.git/werkator/.werkator.yml`, so the committed configuration keeps the gates for forge-backed environments.
|
||||
|
||||
### Notes on `builds` (build definitions)
|
||||
|
||||
@@ -334,7 +334,7 @@ Triggers: `onPush: true` builds every new commit of the selected branches; `atTi
|
||||
A slot may also be written as `??:MM` — that minute of every hour, expanded to its 24 slots, so the build runs hourly.
|
||||
Only the latest due slot of a day triggers, so slots missed while the server was down are skipped instead of piling up, and a slot whose pool is still building is retried on the next poll cycle until it succeeds.
|
||||
A definition may have both; one with neither never triggers automatically — which is how `builds.default` is written when it is meant as a settings base only.
|
||||
GitTally logs a warning once when no definition has a trigger at all, because such an instance never builds anything on its own.
|
||||
Werkator logs a warning once when no definition has a trigger at all, because such an instance never builds anything on its own.
|
||||
|
||||
Selector: `trigger.branches` lists branch names or glob patterns (`*` matches any characters, also across `/`); empty selects all origin branches.
|
||||
A pattern prefixed with `!` excludes instead, and an exclusion always wins regardless of order — `["*", "!master"]` is every branch but master.
|
||||
@@ -343,7 +343,7 @@ That is how a branch gets a build of its own without being built by the default
|
||||
Both parts combine as an intersection.
|
||||
|
||||
Settings: `buildCommand`, `cleanCommand`, `artifactDirs`, `stdoutLog`/`stderrLog`, `requirePullRequest`, `statusContext`, and `docker` with all its keys.
|
||||
A definition carries the complete description of its build; unset keys fall back to `builds.default` and then to GitTally's own defaults.
|
||||
A definition carries the complete description of its build; unset keys fall back to `builds.default` and then to Werkator's own defaults.
|
||||
`requirePullRequest`, `statusContext`, `docker.enabled`, and `docker.network` are pinned (master-pinned, see [the branch layer](#the-branch-layer-a-branch-describes-its-own-ci)): they are read from the repo install/project config even when a branch sets them in its own committed config.
|
||||
Inheritance from `builds.default` covers the settings only — the `trigger` block says when and where *this* build runs and is never inherited.
|
||||
Definitions are part of the branch layer: a branch may add its own and override those from the project config, for its own builds only.
|
||||
@@ -353,9 +353,9 @@ The implicit `default` build (`onPush: true`, all branches) preserves the behavi
|
||||
The `default` build records under the plain branch name; every other build records under `<branch>@<name>` with its own row in the branches view (sorted after its branch), its own `retentionPerBranch` count, latest status, and permanent latest-green artifact link.
|
||||
The URL key is the sanitized pool name — `master@pitest` is served as `/branches/master_pitest/…`.
|
||||
The pools live as long as the underlying branch exists on origin.
|
||||
Restart, `gittally retry`, and the startup recovery re-run a build under its recorded definition, resolving the settings from the current configuration — the job definition is the source of truth, not the historical run.
|
||||
Restart, `werkator retry`, and the startup recovery re-run a build under its recorded definition, resolving the settings from the current configuration — the job definition is the source of truth, not the historical run.
|
||||
The builds still run in their branch's worktree, one build per branch at a time.
|
||||
The Gitea commit status is reported per commit under `gitea.statusContext`, so two builds of the same commit overwrite each other's check — give the second one its own `statusContext` (`GitTally/quick`, say), or keep them apart with an exclusion pattern.
|
||||
The Gitea commit status is reported per commit under `gitea.statusContext`, so two builds of the same commit overwrite each other's check — give the second one its own `statusContext` (`werkator/quick`, say), or keep them apart with an exclusion pattern.
|
||||
|
||||
The concurrency limit that used to live in this section moved to `executor.maxConcurrent` without an alias.
|
||||
A leftover `builds.maxConcurrent` key (or any other scalar where a definition belongs) is ignored with a warning, not a startup failure — a committed config cannot always be changed right away.
|
||||
@@ -378,7 +378,7 @@ To migrate, move `branches.default` to `builds.default`, add `onPush: true`, and
|
||||
### Notes on `watcher.fastForwardLocalRefs`
|
||||
|
||||
Builds run in worktrees that share the primary checkout's `.git`, so a build tool can read `refs/heads/*` there.
|
||||
GitTally itself never needs those refs to be current — it builds the commit `refs/remotes/origin/<branch>` points at — but build tools do.
|
||||
Werkator itself never needs those refs to be current — it builds the commit `refs/remotes/origin/<branch>` points at — but build tools do.
|
||||
A common case is a check that refuses to run when the local main branch differs from its origin counterpart; without this key it would fail on every build once origin moved on, because nothing would ever advance the local ref.
|
||||
|
||||
The fast-forward runs at the end of the poll cycle, after the due branches were enqueued.
|
||||
@@ -390,20 +390,20 @@ The branch checked out in the primary checkout is advanced with `git merge --ff-
|
||||
|
||||
### Notes on `builds.<name>.docker`
|
||||
|
||||
With `docker.enabled`, GitTally shells out to the `docker` CLI; the `docker` command must be on the `PATH`.
|
||||
With `docker.enabled`, Werkator shells out to the `docker` CLI; the `docker` command must be on the `PATH`.
|
||||
When `dockerfile` is set, the image is (re)built whenever the Dockerfile content, its path, or the context path changed.
|
||||
Staleness is tracked via the image label `org.gittally.build-inputs-sha256`.
|
||||
A Gradle cache volume `gittally-gradle-<repo-key>` is created per repository and mounted as `GRADLE_USER_HOME`.
|
||||
Staleness is tracked via the image label `org.werkator.build-inputs-sha256`.
|
||||
A Gradle cache volume `werkator-gradle-<repo-key>` is created per repository and mounted as `GRADLE_USER_HOME`.
|
||||
The build worktree is bind-mounted into the container; after each command the ownership of `build/` and `.gradle/` is repaired to the host user.
|
||||
Git works inside the container: the primary repository's `.git` is mounted read-only (so build steps can run read-only git commands like `git log` or `git describe`), with `.git/gittally/` masked by an empty tmpfs so the build can never read the machine config (`git.token`) or the control token.
|
||||
Note that the rest of `.git` — including `.git/config` — is visible to builds; GitTally never stores credentials there, and neither should you.
|
||||
Git works inside the container: the primary repository's `.git` is mounted read-only (so build steps can run read-only git commands like `git log` or `git describe`), with `.git/werkator/` masked by an empty tmpfs so the build can never read the machine config (`git.token`) or the control token.
|
||||
Note that the rest of `.git` — including `.git/config` — is visible to builds; Werkator never stores credentials there, and neither should you.
|
||||
The Docker socket is mounted into the container and `DOCKER_HOST`/`TESTCONTAINERS_*` variables are set, so Testcontainers-based builds work inside the container.
|
||||
All GitTally containers carry `org.hoennig.gittally` labels; stale build containers of the repository are removed before the first Docker build after a restart.
|
||||
All Werkator containers carry `org.hoennig.werkator` labels; stale build containers of the repository are removed before the first Docker build after a restart.
|
||||
|
||||
## `.git/gittally/.gittally.yml` (not committed)
|
||||
## `.git/werkator/.werkator.yml` (not committed)
|
||||
|
||||
```yaml
|
||||
# Machine- or user-specific overrides and secrets. Keys here win over .gittally.yml.
|
||||
# Machine- or user-specific overrides and secrets. Keys here win over .werkator.yml.
|
||||
git:
|
||||
account: my-user # technical username for git HTTPS authentication
|
||||
token: glpat-xxxxxxxxxxxxxxxxxxxx # Gitea API token — never commit this
|
||||
|
||||
+60
-60
@@ -1,8 +1,8 @@
|
||||
# GitTally Deployment
|
||||
# Werkator Deployment
|
||||
|
||||
This document describes how to run GitTally as a permanent service.
|
||||
This document describes how to run Werkator as a permanent service.
|
||||
The recommended setup is a systemd user service behind an existing reverse proxy.
|
||||
By default GitTally does not manage nginx or TLS certificates itself; it relies on the host's existing web server and certbot.
|
||||
By default Werkator does not manage nginx or TLS certificates itself; it relies on the host's existing web server and certbot.
|
||||
For hosts without one, an opt-in managed nginx/TLS container is available, see [Hosts Without a Reverse Proxy](#hosts-without-a-reverse-proxy-managed-nginxtls).
|
||||
|
||||
## Prerequisites
|
||||
@@ -19,14 +19,14 @@ Build the executable jar once:
|
||||
|
||||
```bash
|
||||
./gradlew build
|
||||
ls build/libs/gittally.jar
|
||||
ls build/libs/werkator.jar
|
||||
```
|
||||
|
||||
Copy the jar to a stable path outside any watched repository, by convention `~/bin/gittally.jar`:
|
||||
Copy the jar to a stable path outside any watched repository, by convention `~/bin/werkator.jar`:
|
||||
|
||||
```bash
|
||||
mkdir -p ~/bin
|
||||
cp build/libs/gittally.jar ~/bin/gittally.jar
|
||||
cp build/libs/werkator.jar ~/bin/werkator.jar
|
||||
```
|
||||
|
||||
The systemd unit generated below points at the jar that was used to run `init --systemd`.
|
||||
@@ -34,41 +34,41 @@ So always run it via the stable path, not via `build/libs/`.
|
||||
|
||||
## Install the Service
|
||||
|
||||
Initialize GitTally in the repository to watch (see [bootstrapping.md](bootstrapping.md) for details):
|
||||
Initialize Werkator in the repository to watch (see [bootstrapping.md](bootstrapping.md) for details):
|
||||
|
||||
```bash
|
||||
cd /path/to/repo
|
||||
java -jar ~/bin/gittally.jar init
|
||||
# fill in git.account and git.token in .git/gittally/.gittally.yml
|
||||
# review .gittally.yml
|
||||
java -jar ~/bin/werkator.jar init
|
||||
# fill in git.account and git.token in .git/werkator/.werkator.yml
|
||||
# review .werkator.yml
|
||||
```
|
||||
|
||||
Generate the systemd user unit:
|
||||
|
||||
```bash
|
||||
java -jar ~/bin/gittally.jar init --systemd
|
||||
java -jar ~/bin/werkator.jar init --systemd
|
||||
```
|
||||
|
||||
This writes `.git/gittally/gittally-<repo-name>.service`, `.git/gittally/gittally.env`, and the nightly Docker cleanup units (`gittally-docker-prune.service`/`.timer`), and prints the install commands:
|
||||
This writes `.git/werkator/werkator-<repo-name>.service`, `.git/werkator/werkator.env`, and the nightly Docker cleanup units (`werkator-docker-prune.service`/`.timer`), and prints the install commands:
|
||||
|
||||
```bash
|
||||
ln -sf /path/to/repo/.git/gittally/gittally-<repo-name>.service ~/.config/systemd/user/gittally-<repo-name>.service
|
||||
ln -sf /path/to/repo/.git/gittally/gittally-docker-prune.service ~/.config/systemd/user/gittally-docker-prune.service
|
||||
ln -sf /path/to/repo/.git/gittally/gittally-docker-prune.timer ~/.config/systemd/user/gittally-docker-prune.timer
|
||||
ln -sf /path/to/repo/.git/werkator/werkator-<repo-name>.service ~/.config/systemd/user/werkator-<repo-name>.service
|
||||
ln -sf /path/to/repo/.git/werkator/werkator-docker-prune.service ~/.config/systemd/user/werkator-docker-prune.service
|
||||
ln -sf /path/to/repo/.git/werkator/werkator-docker-prune.timer ~/.config/systemd/user/werkator-docker-prune.timer
|
||||
systemctl --user daemon-reload
|
||||
systemctl --user enable --now gittally-<repo-name>.service
|
||||
systemctl --user enable --now gittally-docker-prune.timer
|
||||
systemctl --user enable --now werkator-<repo-name>.service
|
||||
systemctl --user enable --now werkator-docker-prune.timer
|
||||
```
|
||||
|
||||
The unit runs `java -jar ~/bin/gittally.jar server` with the repository as working directory and `Restart=always`.
|
||||
The unit runs `java -jar ~/bin/werkator.jar server` with the repository as working directory and `Restart=always`.
|
||||
The unit name contains the repository name, so several repositories can be served by one host, each with its own service and port.
|
||||
|
||||
### Nightly Docker Cleanup
|
||||
|
||||
The `gittally-docker-prune.timer` runs `docker system prune -af` every night at 02:00 (host time), before the usual auto-build slots.
|
||||
The `werkator-docker-prune.timer` runs `docker system prune -af` every night at 02:00 (host time), before the usual auto-build slots.
|
||||
It removes stopped containers, unused images, unused networks, and dangling build cache, so nightly builds start from freshly built images.
|
||||
Unlike the legacy cleanup it does **not** prune volumes — the per-repository Gradle cache volumes survive.
|
||||
The units are host-global (no repository name): with several GitTally instances on one host, every `init --systemd` generates the same files and the symlinks coincide.
|
||||
The units are host-global (no repository name): with several Werkator instances on one host, every `init --systemd` generates the same files and the symlinks coincide.
|
||||
On hosts without a `docker` CLI the service is skipped, not failed (`ExecCondition`).
|
||||
`Persistent=true` catches up a missed run after downtime.
|
||||
|
||||
@@ -84,10 +84,10 @@ loginctl enable-linger "$USER"
|
||||
## Operating the Service
|
||||
|
||||
```bash
|
||||
systemctl --user status gittally-<repo-name>.service # state and last log lines
|
||||
journalctl --user -u gittally-<repo-name>.service -f # follow the log
|
||||
systemctl --user restart gittally-<repo-name>.service # restart (e.g. after config changes)
|
||||
systemctl --user stop gittally-<repo-name>.service # stop
|
||||
systemctl --user status werkator-<repo-name>.service # state and last log lines
|
||||
journalctl --user -u werkator-<repo-name>.service -f # follow the log
|
||||
systemctl --user restart werkator-<repo-name>.service # restart (e.g. after config changes)
|
||||
systemctl --user stop werkator-<repo-name>.service # stop
|
||||
```
|
||||
|
||||
## Updating an Existing Installation
|
||||
@@ -103,67 +103,67 @@ With a jar installation:
|
||||
|
||||
```bash
|
||||
./gradlew build # on the dev machine
|
||||
scp build/libs/gittally.jar <user>@<host>:~/bin/gittally.jar.new
|
||||
scp build/libs/werkator.jar <user>@<host>:~/bin/werkator.jar.new
|
||||
ssh <user>@<host>
|
||||
systemctl --user stop gittally-<repo-name>.service
|
||||
mv ~/bin/gittally.jar ~/bin/gittally.jar.bak # rollback copy
|
||||
mv ~/bin/gittally.jar.new ~/bin/gittally.jar
|
||||
systemctl --user start gittally-<repo-name>.service
|
||||
systemctl --user is-active gittally-<repo-name>.service
|
||||
systemctl --user stop werkator-<repo-name>.service
|
||||
mv ~/bin/werkator.jar ~/bin/werkator.jar.bak # rollback copy
|
||||
mv ~/bin/werkator.jar.new ~/bin/werkator.jar
|
||||
systemctl --user start werkator-<repo-name>.service
|
||||
systemctl --user is-active werkator-<repo-name>.service
|
||||
```
|
||||
|
||||
With a runtime bundle (hosts without Java, see below):
|
||||
|
||||
```bash
|
||||
./gradlew runtimeBundle # on the dev machine
|
||||
scp build/distributions/gittally-runtime-linux-x64.tar.gz <user>@<host>:/tmp/gittally-new.tar.gz
|
||||
scp build/distributions/werkator-runtime-linux-x64.tar.gz <user>@<host>:/tmp/werkator-new.tar.gz
|
||||
ssh <user>@<host>
|
||||
systemctl --user stop gittally-<repo-name>.service
|
||||
mv ~/opt/gittally ~/opt/gittally.bak # rollback copy
|
||||
tar xzf /tmp/gittally-new.tar.gz -C /tmp/ && mv /tmp/gittally ~/opt/gittally
|
||||
~/opt/gittally/bin/gittally --version # expected: the new version
|
||||
systemctl --user start gittally-<repo-name>.service
|
||||
systemctl --user is-active gittally-<repo-name>.service
|
||||
rm -f /tmp/gittally-new.tar.gz
|
||||
systemctl --user stop werkator-<repo-name>.service
|
||||
mv ~/opt/werkator ~/opt/werkator.bak # rollback copy
|
||||
tar xzf /tmp/werkator-new.tar.gz -C /tmp/ && mv /tmp/werkator ~/opt/werkator
|
||||
~/opt/werkator/bin/werkator --version # expected: the new version
|
||||
systemctl --user start werkator-<repo-name>.service
|
||||
systemctl --user is-active werkator-<repo-name>.service
|
||||
rm -f /tmp/werkator-new.tar.gz
|
||||
```
|
||||
|
||||
The tarball unpacks to a `gittally/` directory, so it must not be extracted over `~/opt` directly — unpack it in `/tmp` and move it into place, as above.
|
||||
The tarball unpacks to a `werkator/` directory, so it must not be extracted over `~/opt` directly — unpack it in `/tmp` and move it into place, as above.
|
||||
Rollback is the reverse: stop, remove the new directory (or jar), move `.bak` back, start.
|
||||
|
||||
Then check `https://<public-url>/` for the new version in the footer, and `journalctl --user -u gittally-<repo-name>.service -n 50` for a clean start.
|
||||
Then check `https://<public-url>/` for the new version in the footer, and `journalctl --user -u werkator-<repo-name>.service -n 50` for a clean start.
|
||||
Config file changes are not needed for an update; new keys take their defaults.
|
||||
|
||||
## Control Token
|
||||
|
||||
Viewing is public by design: build states, logs and artifacts are readable without any login, so they can be linked from Gitea, chats or tickets.
|
||||
That is safe as long as the builds themselves handle no real secrets — GitTally has no per-endpoint gating, so an installation whose build output could contain credentials must stay off the public internet (reverse proxy with access control, or `server.bindAddress: 127.0.0.1`).
|
||||
Only the three mutating actions — restart, cancel, delete — require the control token from `.git/gittally/control-token`, a random secret the server generates on first start (mode `0600`; delete the file to rotate it).
|
||||
That is safe as long as the builds themselves handle no real secrets — Werkator has no per-endpoint gating, so an installation whose build output could contain credentials must stay off the public internet (reverse proxy with access control, or `server.bindAddress: 127.0.0.1`).
|
||||
Only the three mutating actions — restart, cancel, delete — require the control token from `.git/werkator/control-token`, a random secret the server generates on first start (mode `0600`; delete the file to rotate it).
|
||||
|
||||
The token is never embedded in a page.
|
||||
The first time you press one of the control buttons, the browser asks for it once and keeps it in `localStorage` for that browser; a rejected token is dropped and asked for again.
|
||||
Read it on the host:
|
||||
|
||||
```bash
|
||||
cat ~/<repo>/.git/gittally/control-token
|
||||
cat ~/<repo>/.git/werkator/control-token
|
||||
```
|
||||
|
||||
For scripts, pass it as a header — it is not accepted as a query parameter, because URLs end up in access logs and browser history:
|
||||
|
||||
```bash
|
||||
curl -X POST -H "X-GitTally-Token: $(cat .git/gittally/control-token)" \
|
||||
curl -X POST -H "X-werkator-Token: $(cat .git/werkator/control-token)" \
|
||||
"https://ci.example.org/api/builds/restart?branch=main"
|
||||
```
|
||||
|
||||
## Environment File
|
||||
|
||||
`.git/gittally/gittally.env` is loaded by the unit as `EnvironmentFile`.
|
||||
`.git/werkator/werkator.env` is loaded by the unit as `EnvironmentFile`.
|
||||
It only tunes the JVM process, e.g. `JAVA_OPTS=-Xmx256m`.
|
||||
All GitTally configuration lives in the YAML files described in [configuration.md](configuration.md), not in environment variables.
|
||||
All Werkator configuration lives in the YAML files described in [configuration.md](configuration.md), not in environment variables.
|
||||
`init --systemd` never overwrites an existing environment file.
|
||||
|
||||
## Reverse Proxy (nginx)
|
||||
|
||||
Bind GitTally to localhost — the default since v0.9.9 — and set the public URL in `.gittally.yml`:
|
||||
Bind Werkator to localhost — the default since v0.9.9 — and set the public URL in `.werkator.yml`:
|
||||
|
||||
```yaml
|
||||
server:
|
||||
@@ -204,39 +204,39 @@ This replaces the legacy script's managed nginx/Let's Encrypt Docker container f
|
||||
## Hosts Without a Java Runtime (Runtime Bundle)
|
||||
|
||||
Some hosts provide git and Docker but no Java runtime and no way to install one, e.g. Hostsharing container servers.
|
||||
For these, GitTally ships as a self-contained runtime bundle: a jlink-trimmed JRE, `gittally.jar`, and a launcher script in one tarball (ADR 0006).
|
||||
For these, Werkator ships as a self-contained runtime bundle: a jlink-trimmed JRE, `werkator.jar`, and a launcher script in one tarball (ADR 0006).
|
||||
|
||||
Build the bundle on a Linux x86_64 machine whose glibc is not newer than the target's:
|
||||
|
||||
```bash
|
||||
./gradlew runtimeBundle
|
||||
ls build/distributions/gittally-runtime-linux-x64.tar.gz
|
||||
ls build/distributions/werkator-runtime-linux-x64.tar.gz
|
||||
```
|
||||
|
||||
Copy and unpack it on the target host, by convention to `~/opt/gittally`:
|
||||
Copy and unpack it on the target host, by convention to `~/opt/werkator`:
|
||||
|
||||
```bash
|
||||
scp build/distributions/gittally-runtime-linux-x64.tar.gz user@host:/tmp/
|
||||
ssh user@host 'mkdir -p ~/opt && tar -xzf /tmp/gittally-runtime-linux-x64.tar.gz -C ~/opt'
|
||||
scp build/distributions/werkator-runtime-linux-x64.tar.gz user@host:/tmp/
|
||||
ssh user@host 'mkdir -p ~/opt && tar -xzf /tmp/werkator-runtime-linux-x64.tar.gz -C ~/opt'
|
||||
```
|
||||
|
||||
Then use `~/opt/gittally/bin/gittally` wherever this document says `java -jar ~/bin/gittally.jar`:
|
||||
Then use `~/opt/werkator/bin/werkator` wherever this document says `java -jar ~/bin/werkator.jar`:
|
||||
|
||||
```bash
|
||||
cd /path/to/repo
|
||||
~/opt/gittally/bin/gittally init
|
||||
~/opt/gittally/bin/gittally init --systemd
|
||||
~/opt/werkator/bin/werkator init
|
||||
~/opt/werkator/bin/werkator init --systemd
|
||||
```
|
||||
|
||||
`init --systemd` detects the bundle automatically: the generated unit's `ExecStart` points at the bundle's `jre/bin/java` and `lib/gittally.jar`, so the install commands printed by `init --systemd` work unchanged.
|
||||
`init --systemd` detects the bundle automatically: the generated unit's `ExecStart` points at the bundle's `jre/bin/java` and `lib/werkator.jar`, so the install commands printed by `init --systemd` work unchanged.
|
||||
`JAVA_OPTS` from the environment file applies as usual.
|
||||
|
||||
To update GitTally, stop the service, unpack the new bundle over `~/opt/gittally`, and restart the service.
|
||||
To update Werkator, stop the service, unpack the new bundle over `~/opt/werkator`, and restart the service.
|
||||
|
||||
## Hosts Without a Reverse Proxy (Managed nginx/TLS)
|
||||
|
||||
Some hosts provide Docker but no root access and no host web server, e.g. Hostsharing managed container environments.
|
||||
For these, GitTally can manage its own nginx+certbot Docker container (ADR 0005).
|
||||
For these, Werkator can manage its own nginx+certbot Docker container (ADR 0005).
|
||||
This is opt-in; where a host web server exists, prefer the reverse-proxy setup above.
|
||||
|
||||
Enable it in the server section of the configuration:
|
||||
@@ -252,12 +252,12 @@ server:
|
||||
letsencryptEmail: admin@example.org
|
||||
```
|
||||
|
||||
On server start, GitTally writes the nginx configuration, starts a labelled nginx container publishing `httpPort` and `httpsPort`, obtains a Let's Encrypt certificate via a certbot container (webroot mode), and restarts nginx with the full HTTPS configuration.
|
||||
On server start, Werkator writes the nginx configuration, starts a labelled nginx container publishing `httpPort` and `httpsPort`, obtains a Let's Encrypt certificate via a certbot container (webroot mode), and restarts nginx with the full HTTPS configuration.
|
||||
A renewal check runs daily; certificates and nginx state persist in `server.nginx.stateDir` across restarts.
|
||||
On shutdown the container is removed.
|
||||
All nginx and certificate failures are non-fatal warnings — the plain HTTP server keeps running without the proxy.
|
||||
|
||||
`serverName` must be a public DNS name pointing at the host, reachable from the internet on port 80/443 (directly or via a port forward to `httpPort`/`httpsPort`), otherwise the ACME challenge fails.
|
||||
The nginx container cannot reach `localhost` of the host, so the proxy upstream defaults to `serverName`; set `server.nginx.upstreamHost` if the host is reachable under a different name from inside containers.
|
||||
With the managed nginx, set `server.bindAddress: 0.0.0.0` explicitly (or an address reachable from the Docker network) — the default `127.0.0.1` makes GitTally unreachable for the proxy container.
|
||||
With the managed nginx, set `server.bindAddress: 0.0.0.0` explicitly (or an address reachable from the Docker network) — the default `127.0.0.1` makes Werkator unreachable for the proxy container.
|
||||
See [configuration.md](configuration.md) for all `server.nginx.*` keys.
|
||||
|
||||
+19
-19
@@ -1,13 +1,13 @@
|
||||
#!/usr/bin/env bash
|
||||
# Example: set up a GitTally instance that watches and builds GitTally itself.
|
||||
# Run from inside a working checkout of the gittally repository.
|
||||
# Example: set up a Werkator instance that watches and builds Werkator itself.
|
||||
# Run from inside a working checkout of the Werkator repository.
|
||||
#
|
||||
# Usage:
|
||||
# GIT_ACCOUNT=mi GIT_TOKEN=xxxx ./docs/examples/setup-gittally-selfhost.sh
|
||||
# GIT_ACCOUNT=mi GIT_TOKEN=xxxx ./docs/examples/setup-werkator-selfhost.sh
|
||||
# (both empty is fine for a public origin — commit statuses just won't be published)
|
||||
set -euo pipefail
|
||||
|
||||
INSTALL_DIR="${INSTALL_DIR:-$HOME/gittally-selfhost}"
|
||||
INSTALL_DIR="${INSTALL_DIR:-$HOME/werkator-selfhost}"
|
||||
GIT_ACCOUNT="${GIT_ACCOUNT:-}" # technical Gitea user for HTTPS fetch + status API
|
||||
GIT_TOKEN="${GIT_TOKEN:-}" # Gitea API token — stays in the uncommitted config file
|
||||
SERVER_PORT="${SERVER_PORT:-18080}"
|
||||
@@ -15,45 +15,45 @@ SERVER_PORT="${SERVER_PORT:-18080}"
|
||||
DEV_CHECKOUT=$(git rev-parse --show-toplevel)
|
||||
ORIGIN_URL="${ORIGIN_URL:-$(git -C "$DEV_CHECKOUT" remote get-url origin)}"
|
||||
|
||||
# 1. Build the GitTally jar — the last Gradle run you ever start by hand.
|
||||
# 1. Build the Werkator jar — the last Gradle run you ever start by hand.
|
||||
(cd "$DEV_CHECKOUT" && ./gradlew --console=plain build)
|
||||
|
||||
# 2. Dedicated clone: builds run in worktrees under its .git/gittally/worktrees,
|
||||
# 2. Dedicated clone: builds run in worktrees under its .git/werkator/worktrees,
|
||||
# completely separate from your dev checkout.
|
||||
mkdir -p "$INSTALL_DIR"
|
||||
cp "$DEV_CHECKOUT/build/libs/gittally.jar" "$INSTALL_DIR/gittally.jar"
|
||||
cp "$DEV_CHECKOUT/build/libs/werkator.jar" "$INSTALL_DIR/werkator.jar"
|
||||
if [ ! -d "$INSTALL_DIR/repo/.git" ]; then
|
||||
git clone "$ORIGIN_URL" "$INSTALL_DIR/repo"
|
||||
fi
|
||||
cd "$INSTALL_DIR/repo"
|
||||
|
||||
# 3. Generate the config templates; existing files are kept. The clone already
|
||||
# carries the committed .gittally.yml, so this only creates the machine config
|
||||
# (.git/gittally/.gittally.yml).
|
||||
java -jar "$INSTALL_DIR/gittally.jar" init
|
||||
# carries the committed .werkator.yml, so this only creates the machine config
|
||||
# (.git/werkator/.werkator.yml).
|
||||
java -jar "$INSTALL_DIR/werkator.jar" init
|
||||
|
||||
# 4. Machine-specific overrides and secrets (.git/gittally/ is never committed;
|
||||
# this file deep-merges over .gittally.yml and wins).
|
||||
cat > .git/gittally/.gittally.yml <<EOF
|
||||
# 4. Machine-specific overrides and secrets (.git/werkator/ is never committed;
|
||||
# this file deep-merges over .werkator.yml and wins).
|
||||
cat > .git/werkator/.werkator.yml <<EOF
|
||||
git:
|
||||
account: "$GIT_ACCOUNT"
|
||||
token: "$GIT_TOKEN"
|
||||
server:
|
||||
port: $SERVER_PORT
|
||||
EOF
|
||||
chmod 600 .git/gittally/.gittally.yml
|
||||
chmod 600 .git/werkator/.werkator.yml
|
||||
|
||||
# The committed .gittally.yml already builds GitTally itself:
|
||||
# The committed .werkator.yml already builds Werkator itself:
|
||||
# buildCommand: ./gradlew --console=plain --no-daemon test
|
||||
# artifactDirs: [build/reports]
|
||||
|
||||
# 5. Optional kick-start: put the local ref one commit behind origin so the very
|
||||
# first poll triggers a build — otherwise GitTally waits for the next push.
|
||||
# first poll triggers a build — otherwise Werkator waits for the next push.
|
||||
# Builds never move this ref or touch this checkout, so lagging is harmless.
|
||||
git reset --hard --quiet HEAD~1 || true
|
||||
|
||||
# 6. Run it (Ctrl-C stops it cleanly). For a permanent setup, run
|
||||
# `java -jar "$INSTALL_DIR/gittally.jar" init --systemd` here instead and follow
|
||||
# `java -jar "$INSTALL_DIR/werkator.jar" init --systemd` here instead and follow
|
||||
# docs/deployment.md — the generated unit points at this jar and repo.
|
||||
echo "GitTally self-host: http://localhost:$SERVER_PORT/ — watching $ORIGIN_URL"
|
||||
exec java -jar "$INSTALL_DIR/gittally.jar" server
|
||||
echo "Werkator self-host: http://localhost:$SERVER_PORT/ — watching $ORIGIN_URL"
|
||||
exec java -jar "$INSTALL_DIR/werkator.jar" server
|
||||
+14
-14
@@ -1,30 +1,30 @@
|
||||
#!/usr/bin/env bash
|
||||
# Example: start a GitTally test server watching a scratch repository with a fake build.
|
||||
# Example: start a Werkator test server watching a scratch repository with a fake build.
|
||||
# This is the setup used for the manual UI/API smoke tests during development:
|
||||
# a local bare origin (with a second branch for the Branches view), a slow fake
|
||||
# build with live log output and a demo report artifact, and a fast poll
|
||||
# interval — no Gitea, no credentials, no Docker.
|
||||
#
|
||||
# Usage:
|
||||
# ./docs/examples/setup-gittally-testserver.sh
|
||||
# BUILD_SECONDS=5 SERVER_PORT=18981 ./docs/examples/setup-gittally-testserver.sh
|
||||
# ./docs/examples/setup-werkator-testserver.sh
|
||||
# BUILD_SECONDS=5 SERVER_PORT=18981 ./docs/examples/setup-werkator-testserver.sh
|
||||
#
|
||||
# While the server runs, trigger builds by pushing from the "work" clone:
|
||||
# git -C ~/gittally-testserver/work commit --allow-empty -m "trigger build" && git -C ~/gittally-testserver/work push
|
||||
# git -C ~/werkator-testserver/work commit --allow-empty -m "trigger build" && git -C ~/werkator-testserver/work push
|
||||
# A commit message containing "[fail]" makes the fake build fail;
|
||||
# pushing a new branch exercises the new-origin-branch path.
|
||||
set -euo pipefail
|
||||
|
||||
INSTALL_DIR="${INSTALL_DIR:-$HOME/gittally-testserver}"
|
||||
INSTALL_DIR="${INSTALL_DIR:-$HOME/werkator-testserver}"
|
||||
SERVER_PORT="${SERVER_PORT:-18980}"
|
||||
export BUILD_SECONDS="${BUILD_SECONDS:-25}" # inherited by the build process at runtime
|
||||
|
||||
DEV_CHECKOUT=$(git rev-parse --show-toplevel)
|
||||
|
||||
# 1. Build the GitTally jar.
|
||||
# 1. Build the Werkator jar.
|
||||
(cd "$DEV_CHECKOUT" && ./gradlew --console=plain build)
|
||||
mkdir -p "$INSTALL_DIR"
|
||||
cp "$DEV_CHECKOUT/build/libs/gittally.jar" "$INSTALL_DIR/gittally.jar"
|
||||
cp "$DEV_CHECKOUT/build/libs/werkator.jar" "$INSTALL_DIR/werkator.jar"
|
||||
|
||||
# 2. Scratch bare origin plus a "work" clone for triggering builds by pushing.
|
||||
if [ ! -d "$INSTALL_DIR/origin.git" ]; then
|
||||
@@ -39,7 +39,7 @@ if ! git -C "$INSTALL_DIR/work" rev-parse --quiet --verify HEAD >/dev/null; then
|
||||
cat > "$INSTALL_DIR/work/fake-build.sh" <<'EOF'
|
||||
#!/usr/bin/env bash
|
||||
# Fake build: visible progress for the live log, then a demo report artifact.
|
||||
# GitTally exports `branch`; BUILD_SECONDS is inherited from the server process.
|
||||
# Werkator exports `branch`; BUILD_SECONDS is inherited from the server process.
|
||||
set -euo pipefail
|
||||
echo "fake build of branch ${branch:-unknown} at commit $(git rev-parse --short HEAD)"
|
||||
if git log -1 --pretty=%s | grep -qF '[fail]'; then
|
||||
@@ -56,7 +56,7 @@ printf '<!DOCTYPE html><html><body><h1>Demo Report</h1><p>branch %s, commit %s</
|
||||
echo "fake build done"
|
||||
EOF
|
||||
chmod +x "$INSTALL_DIR/work/fake-build.sh"
|
||||
cat > "$INSTALL_DIR/work/.gittally.yml" <<'EOF'
|
||||
cat > "$INSTALL_DIR/work/.werkator.yml" <<'EOF'
|
||||
watcher:
|
||||
pollInterval: 5s
|
||||
|
||||
@@ -67,7 +67,7 @@ branches:
|
||||
artifactDirs:
|
||||
- build/reports
|
||||
EOF
|
||||
git -C "$INSTALL_DIR/work" add fake-build.sh .gittally.yml
|
||||
git -C "$INSTALL_DIR/work" add fake-build.sh .werkator.yml
|
||||
git -C "$INSTALL_DIR/work" commit --quiet -m "fake build setup"
|
||||
git -C "$INSTALL_DIR/work" commit --quiet --allow-empty -m "kick-start build"
|
||||
git -C "$INSTALL_DIR/work" push --quiet origin main
|
||||
@@ -88,8 +88,8 @@ if [ ! -d "$INSTALL_DIR/repo/.git" ]; then
|
||||
git clone --quiet "$INSTALL_DIR/origin.git" "$INSTALL_DIR/repo"
|
||||
fi
|
||||
cd "$INSTALL_DIR/repo"
|
||||
mkdir -p .git/gittally
|
||||
cat > .git/gittally/.gittally.yml <<EOF
|
||||
mkdir -p .git/werkator
|
||||
cat > .git/werkator/.werkator.yml <<EOF
|
||||
server:
|
||||
port: $SERVER_PORT
|
||||
bindAddress: 127.0.0.1
|
||||
@@ -101,8 +101,8 @@ git reset --hard --quiet HEAD~1 || true
|
||||
|
||||
# 5. Run it (Ctrl-C stops it cleanly).
|
||||
echo
|
||||
echo "GitTally test server: http://localhost:$SERVER_PORT/"
|
||||
echo "Werkator test server: http://localhost:$SERVER_PORT/"
|
||||
echo "Trigger a build: git -C $INSTALL_DIR/work commit --allow-empty -m 'trigger build' && git -C $INSTALL_DIR/work push"
|
||||
echo "Trigger a failure: same with commit message 'trigger [fail]'"
|
||||
echo
|
||||
exec java -jar "$INSTALL_DIR/gittally.jar" server
|
||||
exec java -jar "$INSTALL_DIR/werkator.jar" server
|
||||
@@ -1,94 +0,0 @@
|
||||
# Migration from the Legacy Script
|
||||
|
||||
The bash script `legacy/gitTally` is deprecated and replaced by this application.
|
||||
This document maps the legacy environment-variable configuration to the YAML configuration and lists the manual migration steps.
|
||||
See [configuration.md](configuration.md) for the full configuration reference and [deployment.md](deployment.md) for the new service setup.
|
||||
|
||||
## Configuration Mapping
|
||||
|
||||
Legacy configuration came from environment variables (`gitTally --env` template, sourced env files).
|
||||
The new configuration lives in two YAML files: `.gittally.yml` (committed) and `.git/gittally/.gittally.yml` (machine-specific, secrets).
|
||||
|
||||
Build-level keys below live in a build definition under `builds.<name>`; use `builds.default` for what used to be
|
||||
the global value — it is the base every other definition inherits its settings from.
|
||||
|
||||
| Legacy environment variable | New YAML key |
|
||||
|---|---|
|
||||
| `GITTALLY_BUILD_COMMAND` | `builds.<name>.buildCommand` |
|
||||
| `GITTALLY_BUILD_CLEAN_COMMAND` | `builds.<name>.cleanCommand` |
|
||||
| `GITTALLY_BUILD_ARTEFACT_DIRS` | `builds.<name>.artifactDirs` — YAML list instead of `;`-separated |
|
||||
| `GITTALLY_BUILD_STDOUT_LOG` | `builds.<name>.stdoutLog` |
|
||||
| `GITTALLY_BUILD_STDERR_LOG` | `builds.<name>.stderrLog` |
|
||||
| `GITTALLY_NEW_BRANCH_COMMIT_MAX_AGE` | `watcher.newBranchMaxAge` |
|
||||
| `GITTALLY_BUILD_DOCKER_IMAGE` | `builds.<name>.docker.image` — also set `docker.enabled: true` (replaces the `--docker` flag) |
|
||||
| `GITTALLY_BUILD_DOCKERFILE` | `builds.<name>.docker.dockerfile` |
|
||||
| `GITTALLY_BUILD_DOCKER_CONTEXT` | `builds.<name>.docker.context` |
|
||||
| `GITTALLY_BUILD_DOCKER_NETWORK` | `builds.<name>.docker.network` — default is now Docker's default network, not `host` |
|
||||
| `GITTALLY_BUILD_DOCKER_ENV` | `builds.<name>.docker.env` — YAML map instead of space-separated assignments |
|
||||
| `GITTALLY_ARTIFACT_SERVER_PORT` | `server.port` |
|
||||
| `GITTALLY_ARTIFACT_SERVER_BIND_ADDRESS` | `server.bindAddress` |
|
||||
| `GITTALLY_ARTIFACT_PUBLIC_BASE_URL` | `server.publicBaseUrl` |
|
||||
| `GITTALLY_ARTIFACT_BUILD_RETENTION_PER_BRANCH` | `artifacts.retentionPerBranch` for a count, `artifacts.retentionMaxAge` for a legacy age value (`h`/`d` suffix); unlike legacy, both limits can be combined |
|
||||
| `GITTALLY_IMPRESSUM_URL` | `server.impressumUrl` |
|
||||
| `GITTALLY_AUTO_BUILD_BRANCHES` | a build definition with `branches: [...]` selecting them |
|
||||
| `GITTALLY_AUTO_BUILD_TIMES` | `builds.<name>.atTimes` — YAML list of UTC `HH:MM` slots |
|
||||
| `GITTALLY_GITEA_BASE_URL` | `gitea.baseUrl` |
|
||||
| `GITTALLY_GITEA_OWNER` | `gitea.owner` |
|
||||
| `GITTALLY_GITEA_REPO` | `gitea.repo` |
|
||||
| `GITTALLY_GITEA_STATUS_CONTEXT` | `gitea.statusContext` |
|
||||
| `GITTALLY_GITEA_GIT_USERNAME` | `git.account` — in `.git/gittally/.gittally.yml` |
|
||||
| `GITTALLY_GITEA_TOKEN` | `git.token` — in `.git/gittally/.gittally.yml`, never committed |
|
||||
| `GITTALLY_ARTIFACT_NGINX_SERVER_NAME` | `server.nginx.serverName` — also set `server.nginx.enabled: true` (replaces the `--nginx` flag) |
|
||||
| `GITTALLY_ARTIFACT_NGINX_HTTP_PORT` | `server.nginx.httpPort` |
|
||||
| `GITTALLY_ARTIFACT_NGINX_HTTPS_PORT` | `server.nginx.httpsPort` |
|
||||
| `GITTALLY_ARTIFACT_NGINX_UPSTREAM_HOST` | `server.nginx.upstreamHost` |
|
||||
| `GITTALLY_ARTIFACT_NGINX_CONTAINER_NAME` | `server.nginx.containerName` |
|
||||
| `GITTALLY_ARTIFACT_NGINX_STATE_DIR` | `server.nginx.stateDir` |
|
||||
| `GITTALLY_ARTIFACT_LETSENCRYPT_EMAIL` | `server.nginx.letsencryptEmail` |
|
||||
|
||||
New keys without a legacy counterpart: `builds.maxConcurrent`, `artifacts.rootDir`, and `watcher.pollInterval`.
|
||||
|
||||
## Intentionally Not Ported
|
||||
|
||||
- Self-install and self-update (`--install`, `--pull`, `GITTALLY_INSTALL_DIR`) — replaced by jar deployment plus `init --systemd`.
|
||||
- `GITTALLY_BUILD_DOCKER_PREFLIGHT_COMMAND` and `GITTALLY_BUILD_DOCKER_JAVA_TOOL_OPTIONS` — hsadmin-ng-specific; use `builds.<name>.docker.env` if needed.
|
||||
- `HSADMIN_NG_*` environment-variable fallbacks.
|
||||
- Env-file configuration itself — the systemd `EnvironmentFile` now only tunes the JVM (`JAVA_OPTS`).
|
||||
- `GITTALLY_GITEA_DELETED_STATUS_DESCRIPTION`, `GITTALLY_BIN_FORWARD`, `GITTALLY_CONFIG_*` — internal legacy mechanics without a counterpart.
|
||||
|
||||
## Build History
|
||||
|
||||
Legacy build history (`.git/git-watch-origin-and-test/build-results.tsv`) is **not** imported; history starts fresh.
|
||||
The formats differ substantially (TSV vs. JSON with commit metadata and artifact keys), and retention would prune imported rows quickly anyway.
|
||||
Old artifacts under the legacy artifact root remain readable on disk until you delete them.
|
||||
|
||||
## Manual Migration Steps
|
||||
|
||||
When migrating to a **different host**, the legacy instance can keep running in parallel until the new one is verified — then skip step 1 here and stop the legacy service on the old host last.
|
||||
During parallel operation, give the new instance a distinct `gitea.statusContext`, so the two instances do not overwrite each other's commit statuses in Gitea.
|
||||
|
||||
Rename the context back to the canonical one **while no build is running**.
|
||||
The Gitea client reads the config per call, so a rename between a build's `running` and its final status splits that build over two contexts: the old one keeps the `pending` "build running" entry forever, and Gitea's combined status of that commit stays *pending* although the build succeeded.
|
||||
Gitea has no API to delete a commit status; the only way out is to post a closing status for the abandoned context by hand:
|
||||
|
||||
```bash
|
||||
curl -X POST -H "Authorization: token $TOKEN" -H 'Content-Type: application/json' \
|
||||
-d '{"state":"success","context":"<old context>","description":"superseded by <new context>"}' \
|
||||
"$GITEA/api/v1/repos/<owner>/<repo>/statuses/<commit-sha>"
|
||||
```
|
||||
|
||||
1. Stop and remove the legacy service:
|
||||
|
||||
```bash
|
||||
systemctl --user disable --now gitTally.service
|
||||
rm -f ~/.config/systemd/user/gitTally.service
|
||||
systemctl --user daemon-reload
|
||||
```
|
||||
|
||||
2. Build and place the jar as described in [deployment.md](deployment.md).
|
||||
3. In the repository, run `java -jar ~/bin/gittally.jar init`.
|
||||
4. Transfer your settings from the legacy env file into `.gittally.yml` using the table above.
|
||||
5. Put `git.account` and `git.token` into `.git/gittally/.gittally.yml`.
|
||||
6. Verify the effective configuration: `java -jar ~/bin/gittally.jar config:print --full`.
|
||||
7. Install and start the new service: `init --systemd` plus the printed commands, see [deployment.md](deployment.md).
|
||||
8. Optionally clean up legacy state: `.git/git-watch-origin-and-test/` and the legacy artifact root.
|
||||
@@ -1,6 +1,7 @@
|
||||
# Legacy gitTally Analysis
|
||||
# Legacy Werkator Analysis
|
||||
|
||||
Condensed analysis of `legacy/gitTally` (bash, ~6000 lines) as input for the rewrite.
|
||||
Condensed analysis of the legacy bash script (~6000 lines) as input for the rewrite.
|
||||
The script was removed from the tree with the rename to Werkator; its last state is `git show 7f55068^:legacy/gitTally`.
|
||||
Line numbers refer to the legacy script at the time of analysis (version 0.7.8).
|
||||
|
||||
## What the Legacy System Does
|
||||
|
||||
@@ -9,14 +9,14 @@ A tested domain model for build results plus a persistent repository, replacing
|
||||
|
||||
## Design
|
||||
|
||||
Create package `de.hoennig.gittally.build`:
|
||||
Create package `de.hoennig.werkator.build`:
|
||||
|
||||
- `BuildStatus` enum: `PENDING`, `RUNNING`, `SUCCESS`, `FAILED`, `INTERRUPTED`, `CANCELLED`.
|
||||
Add `isTerminal`, `isRestartable` (pending/running/interrupted) properties.
|
||||
- `BuildResult` data class: branch, commit SHA, status, startedAt, duration, artifactKey.
|
||||
Use `java.time.Instant`/`Duration`; format only at the edges.
|
||||
- `BuildResultRepository` interface: append, update status of latest entry for a branch, query latest per branch, query history, delete entry, prune.
|
||||
- `FileBuildResultRepository`: JSON file at `.git/gittally/build-results.json`.
|
||||
- `FileBuildResultRepository`: JSON file at `.git/werkator/build-results.json`.
|
||||
Write atomically (write temp file, then `Files.move` with `ATOMIC_MOVE`).
|
||||
Reuse the Jackson YAML/JSON setup style from `ConfigLoader`.
|
||||
|
||||
@@ -52,7 +52,7 @@ Kotest `FunSpec`, no Spring context needed.
|
||||
|
||||
## Execution Notes (done 2026-07-07)
|
||||
|
||||
Implemented as specified in `de.hoennig.gittally.build`; build green, 19 new tests.
|
||||
Implemented as specified in `de.hoennig.werkator.build`; build green, 19 new tests.
|
||||
Deviations and details:
|
||||
|
||||
- Added `jackson-datatype-jsr310` to `build.gradle.kts` for `Instant`/`Duration` JSON support (ISO-8601 strings).
|
||||
|
||||
@@ -9,7 +9,7 @@ A tested client for the Gitea commit-status API.
|
||||
|
||||
## Design
|
||||
|
||||
Create package `de.hoennig.gittally.gitea`:
|
||||
Create package `de.hoennig.werkator.gitea`:
|
||||
|
||||
- `GiteaClient` using Spring's `RestClient`.
|
||||
- `publishStatus(sha, state, description, targetUrl)` → `POST /api/v1/repos/{owner}/{repo}/statuses/{sha}` with header `Authorization: token <git.token>`; body fields `state`, `context`, `description`, `target_url`.
|
||||
@@ -19,12 +19,12 @@ Create package `de.hoennig.gittally.gitea`:
|
||||
- `isEnabled()` — true only when `gitea.baseUrl`, `gitea.owner`, `gitea.repo`, and `git.token` are configured.
|
||||
All callers must treat a disabled or failing client as non-fatal (log and continue); the legacy behaved the same but failed silently.
|
||||
|
||||
Configuration comes from `GitTallyConfig` (`gitea.*`, `git.token`).
|
||||
Configuration comes from `WerkatorConfig` (`gitea.*`, `git.token`).
|
||||
|
||||
## Out of Scope
|
||||
|
||||
- No callers yet; the build executor (step 04) wires status publishing.
|
||||
- No webhook receiving; GitTally remains poll-based.
|
||||
- No webhook receiving; Werkator remains poll-based.
|
||||
|
||||
## Tests
|
||||
|
||||
@@ -50,4 +50,4 @@ Implemented as designed; deviations and decisions:
|
||||
- `resolveUsername` only requires `gitea.baseUrl` and `git.token`; legacy gated it on the full status-enabled check including owner/repo, which the `/api/v1/user` endpoint does not need.
|
||||
- Responses are read as strings and parsed with a dedicated Jackson `ObjectMapper` instead of RestClient message converters, keeping malformed-JSON handling explicit and independent of converter auto-detection.
|
||||
- The legacy "Build status deleted" description marker is not ported; it belongs to the result-delete feature of later steps.
|
||||
- No config changes were needed: `gitea.*` and `git.token` already exist in `GitTallyConfig`, the `init` templates, and `docs/configuration.md`.
|
||||
- No config changes were needed: `gitea.*` and `git.token` already exist in `WerkatorConfig`, the `init` templates, and `docs/configuration.md`.
|
||||
|
||||
@@ -10,7 +10,7 @@ This step fixes the legacy defect that nothing could observe status changes whil
|
||||
|
||||
## Design
|
||||
|
||||
Create package `de.hoennig.gittally.build` (extends step 01):
|
||||
Create package `de.hoennig.werkator.build` (extends step 01):
|
||||
|
||||
- `BuildExecutor` service; one build at a time (a `ReentrantLock` or single-thread executor replaces the legacy flock file).
|
||||
- `startBuild(branch, commit)` runs asynchronously and returns immediately; expose `currentBuild(): RunningBuild?`.
|
||||
@@ -50,7 +50,7 @@ Consider `builds.timeout` only if trivial; otherwise defer.
|
||||
|
||||
## Execution Notes (done 2026-07-07)
|
||||
|
||||
Implemented as designed in `de.hoennig.gittally.build`; build green, 18 new tests
|
||||
Implemented as designed in `de.hoennig.werkator.build`; build green, 18 new tests
|
||||
(`BuildExecutorTest`, `ProcessBuildRunnerTest`, `ArtifactKeysTest`, plus two new `FileBuildResultRepositoryTest` cases).
|
||||
Deviations and decisions:
|
||||
|
||||
@@ -61,10 +61,10 @@ Deviations and decisions:
|
||||
The flag is checked before each command and after `waitFor`, so a cancel between clean and build commands still records `CANCELLED`.
|
||||
- Artifact key naming (`ArtifactKeys`) was needed here because `BuildResult` requires a key; it follows the legacy scheme (sanitized name + 12-char SHA-256 prefix + sanitized ISO timestamp + hash) using the UTC `Instant`, not local time.
|
||||
Step 05 should reuse it rather than re-implement.
|
||||
- `ArtifactStore` is an interface in the `build` package with a logging `NoOpArtifactStore` placeholder; step 05 replaces the placeholder and implements the real store in `de.hoennig.gittally.artifacts`.
|
||||
- `ArtifactStore` is an interface in the `build` package with a logging `NoOpArtifactStore` placeholder; step 05 replaces the placeholder and implements the real store in `de.hoennig.werkator.artifacts`.
|
||||
- The combined live log is `build.log` inside the per-build staging directory (a temp dir exposed via `RunningBuild.stagingDir`/`liveLogFile`); output is flushed per read chunk so the log grows while the build runs.
|
||||
- Commands run via `bash -c` with the branch name in the environment as `branch`, like legacy `run_build_command`; a failing `cleanCommand` fails the build without running `buildCommand`.
|
||||
- `BuildResultRepository` is wired as a Spring bean (`BuildConfiguration`) at `.git/gittally/build-results.json` relative to the working directory, matching how `ConfigLoader` resolves the override file; `git rev-parse --git-path` style worktree resolution can come later if needed.
|
||||
- `BuildResultRepository` is wired as a Spring bean (`BuildConfiguration`) at `.git/werkator/build-results.json` relative to the working directory, matching how `ConfigLoader` resolves the override file; `git rev-parse --git-path` style worktree resolution can come later if needed.
|
||||
- Gitea `target_url` is not published yet; the artifact page URL scheme only exists from step 07 on.
|
||||
- `builds.timeout` was deferred (not trivial alongside cancellation semantics); no config keys were added or changed.
|
||||
|
||||
@@ -75,9 +75,9 @@ Refactored on request, superseding parts of the notes above:
|
||||
- Builds now run concurrently up to the new config key `builds.maxConcurrent` (default 1), enforced by a global semaphore sized on first use (changing it requires a restart).
|
||||
- At most one build per branch at a time, enforced by one serial worker per branch; a second build of the same branch queues as `PENDING` and runs afterwards ("finish, then next").
|
||||
Whether a new commit should instead cancel the branch's running build is a later, possibly configurable decision (see step 06).
|
||||
- Each branch builds in its own reusable git worktree at `.git/gittally/worktrees/<branchKey>` (`BranchWorkspaces`/`GitWorktreeWorkspaces`), checked out detached at the requested commit — the primary checkout is never touched.
|
||||
- Each branch builds in its own reusable git worktree at `.git/werkator/worktrees/<branchKey>` (`BranchWorkspaces`/`GitWorktreeWorkspaces`), checked out detached at the requested commit — the primary checkout is never touched.
|
||||
Reuse keeps incremental build caches; `cleanCommand` decides how much of them survives.
|
||||
`GitService` gained `worktreeAdd`, `worktreePrune`, and `checkoutDetached` for this.
|
||||
- API change: `currentBuild()` became `currentBuilds(): List<RunningBuild>`, and `cancel()` became `cancel(artifactKey)`; a queued build can be cancelled too and is recorded `CANCELLED` when its worker picks it up.
|
||||
- The Gitea `PENDING` status is now published synchronously in `startBuild`, so queued builds are visible in Gitea while they wait for a slot.
|
||||
- Branch config is still loaded from the primary repository directory, not from the branch's checked-out `.gittally.yml`; honoring the branch's own committed config would be a separate decision.
|
||||
- Branch config is still loaded from the primary repository directory, not from the branch's checked-out `.werkator.yml`; honoring the branch's own committed config would be a separate decision.
|
||||
|
||||
@@ -9,10 +9,10 @@ Persist build artifacts (logs plus configured report directories) with stable na
|
||||
|
||||
## Design
|
||||
|
||||
Create package `de.hoennig.gittally.artifacts`:
|
||||
Create package `de.hoennig.werkator.artifacts`:
|
||||
|
||||
- `ArtifactStore` service implementing the interface stubbed in step 04.
|
||||
- Artifact root: a configurable directory (new key `artifacts.rootDir`), defaulting to `${XDG_STATE_HOME:-~/.local/state}/gittally/artifacts/<repo-key>`.
|
||||
- Artifact root: a configurable directory (new key `artifacts.rootDir`), defaulting to `${XDG_STATE_HOME:-~/.local/state}/werkator/artifacts/<repo-key>`.
|
||||
Do NOT default to `/tmp` like legacy — artifacts vanished on reboot.
|
||||
- Repo key: sanitized absolute repo path (legacy `repository_key`): non `[A-Za-z0-9._-]` → `_`.
|
||||
- Artifact key per build: sanitized branch name + 12-char SHA-256 prefix, plus sanitized start timestamp + hash (legacy `build_artifact_key`); keep this scheme so URLs stay predictable.
|
||||
@@ -28,7 +28,7 @@ Create package `de.hoennig.gittally.artifacts`:
|
||||
## Config
|
||||
|
||||
New key `artifacts.rootDir` (empty = platform default above).
|
||||
Update `GitTallyConfig`, `InitCommand` templates, and `docs/configuration.md` together.
|
||||
Update `WerkatorConfig`, `InitCommand` templates, and `docs/configuration.md` together.
|
||||
|
||||
## Tests
|
||||
|
||||
@@ -43,11 +43,11 @@ Update `GitTallyConfig`, `InitCommand` templates, and `docs/configuration.md` to
|
||||
|
||||
## Execution Notes (done 2026-07-07)
|
||||
|
||||
Implemented as `FileArtifactStore` in `de.hoennig.gittally.artifacts`; build green, 12 new tests
|
||||
Implemented as `FileArtifactStore` in `de.hoennig.werkator.artifacts`; build green, 12 new tests
|
||||
(`FileArtifactStoreTest`, `BuildExecutorArtifactIntegrationTest`, plus a `repoKey` case in `ArtifactKeysTest`).
|
||||
Deviations and decisions:
|
||||
|
||||
- The `ArtifactStore` interface stays in `de.hoennig.gittally.build` (moving it would make `build` depend on `artifacts`).
|
||||
- The `ArtifactStore` interface stays in `de.hoennig.werkator.build` (moving it would make `build` depend on `artifacts`).
|
||||
It gained `prune(keptResults)` and `artifactDir(artifactKey)`; the `NoOpArtifactStore` placeholder was removed.
|
||||
- Interface gap from step 04 resolved by an additional parameter: `persist(build, stagingDir, workspace)`.
|
||||
The store copies the configured `artifactDirs` out of the branch worktree itself, so the archived layout stays store knowledge.
|
||||
@@ -67,5 +67,5 @@ Deviations and decisions:
|
||||
and returns the removed keys.
|
||||
- `artifactDir` rejects keys outside `[A-Za-z0-9._-]+` and anything resolving outside `<root>/branches/` (path traversal).
|
||||
- `artifacts.rootDir` supports a leading `~/` and resolves relative paths against the repository;
|
||||
when empty, the default is `$XDG_STATE_HOME` (or `~/.local/state`) + `/gittally/artifacts/<repo-key>` as designed.
|
||||
when empty, the default is `$XDG_STATE_HOME` (or `~/.local/state`) + `/werkator/artifacts/<repo-key>` as designed.
|
||||
- The bean is wired in `ArtifactsConfiguration` with the working directory defaulting to `.`, mirroring `BuildConfiguration`.
|
||||
|
||||
@@ -9,7 +9,7 @@ Replace the legacy blocking main loop with a non-blocking, observable scheduler.
|
||||
|
||||
## Design
|
||||
|
||||
Create package `de.hoennig.gittally.watcher`:
|
||||
Create package `de.hoennig.werkator.watcher`:
|
||||
|
||||
- `Watcher` component with a fixed-delay poll cycle (Spring `@Scheduled` or a managed executor; enabled only in server/watch mode, not during CLI commands or tests).
|
||||
- One poll cycle, never blocking on a build:
|
||||
@@ -19,7 +19,7 @@ Create package `de.hoennig.gittally.watcher`:
|
||||
4. Start builds for due branches via `startBuild(branch, commit)` (async).
|
||||
The executor prepares a per-branch worktree itself (step 04 amendment) — the watcher must never check out or reset the primary worktree.
|
||||
Multiple branches may build concurrently (`builds.maxConcurrent`); the executor already serializes builds of the same branch, so the watcher only has to avoid enqueueing a branch that is already pending or running.
|
||||
5. Run repository retention pruning and artifact pruning; also remove worktrees under `.git/gittally/worktrees/` of branches no longer on origin (`git worktree remove` or delete + `worktreePrune`).
|
||||
5. Run repository retention pruning and artifact pruning; also remove worktrees under `.git/werkator/worktrees/` of branches no longer on origin (`git worktree remove` or delete + `worktreePrune`).
|
||||
- Decide here (or defer with a note): when a new commit arrives for a branch whose build is still running, keep the current queue-behind behavior or cancel the running build and start fresh — this may become a per-branch config option.
|
||||
- Startup sequence (port of legacy recovery): mark stale running builds interrupted, then enqueue restartable branches.
|
||||
- Auto-builds: per-branch `autoBuild.enabled` + `times` (UTC HH:MM) from the merged `branches` config.
|
||||
@@ -34,7 +34,7 @@ Create package `de.hoennig.gittally.watcher`:
|
||||
## Config
|
||||
|
||||
New key `watcher.pollInterval` (e.g. `10s`, default matching legacy cadence).
|
||||
Update `GitTallyConfig`, `InitCommand` templates, and `docs/configuration.md` together.
|
||||
Update `WerkatorConfig`, `InitCommand` templates, and `docs/configuration.md` together.
|
||||
|
||||
## Tests
|
||||
|
||||
@@ -51,7 +51,7 @@ Update `GitTallyConfig`, `InitCommand` templates, and `docs/configuration.md` to
|
||||
|
||||
## Execution Notes (done 2026-07-07)
|
||||
|
||||
Implemented as designed in `de.hoennig.gittally.watcher`; build green, 23 new tests
|
||||
Implemented as designed in `de.hoennig.werkator.watcher`; build green, 23 new tests
|
||||
(`WatcherTest`, `AutoBuildStateTest`, plus new `DurationParserTest` and `GitServiceTest` cases).
|
||||
Deviations and decisions:
|
||||
|
||||
@@ -72,7 +72,7 @@ Deviations and decisions:
|
||||
- Enqueue precedence per cycle: changed local branches, then recent new origin branches, then due auto-build slots;
|
||||
each branch at most once (an auto-build slot stays untriggered while its branch is pending/running and fires
|
||||
on a later cycle instead of being lost).
|
||||
- Auto-build state lives in `.git/gittally/auto-builds.json` (`FileAutoBuildState`, replaces `auto-builds.tsv`);
|
||||
- Auto-build state lives in `.git/werkator/auto-builds.json` (`FileAutoBuildState`, replaces `auto-builds.tsv`);
|
||||
entries of past days are dropped on write. Slot matching (`AutoBuildSlots`) picks the latest slot at or before
|
||||
the current UTC time, like legacy `auto_build_check`. Only branches named in the `branches` config
|
||||
(other than `default`) can auto-build; `default.autoBuild.enabled` does not extend to unlisted branches.
|
||||
@@ -80,7 +80,7 @@ Deviations and decisions:
|
||||
on origin, after a best-effort fetch (a failing fetch recovers from the last known origin state).
|
||||
A stale latest PENDING entry is marked INTERRUPTED before its replacement build is enqueued,
|
||||
because the executor queue does not survive a restart.
|
||||
- Worktree cleanup deletes `.git/gittally/worktrees/<branchKey>` directories of branches gone from origin
|
||||
- Worktree cleanup deletes `.git/werkator/worktrees/<branchKey>` directories of branches gone from origin
|
||||
(never those of queued or running builds) and then calls `git worktree prune`.
|
||||
- `DurationParser` was extended with `s`/`m` suffixes for `watcher.pollInterval` (it only knew `d`/`h`).
|
||||
- Watcher health is exposed via `Watcher.state(): WatcherState` (running, last poll time, last fetch/poll error,
|
||||
|
||||
@@ -18,7 +18,7 @@ Bootstrapping:
|
||||
- The watcher (step 06) is active only in the `server` profile.
|
||||
- New config keys `server.port` and `server.bindAddress` (defaults 18080 / 0.0.0.0, as legacy).
|
||||
|
||||
JSON API (package `de.hoennig.gittally.server`), replacing the legacy `/control/*` endpoints:
|
||||
JSON API (package `de.hoennig.werkator.server`), replacing the legacy `/control/*` endpoints:
|
||||
|
||||
- `GET /api/builds/latest` — latest build per branch.
|
||||
- `GET /api/builds/history` — all builds, newest first.
|
||||
@@ -54,13 +54,13 @@ After Ctrl-C, `ServerCommand` parks the command thread while the JVM shuts down;
|
||||
Deviations and decisions:
|
||||
|
||||
- The live log tail is a sibling endpoint: `GET /api/builds/current` lists the running builds (with `logSize`), and `GET /api/builds/current/{artifactKey}/log?offset=` fetches the log incrementally, addressed by artifact key as required. Responses are capped at 1 MiB per chunk.
|
||||
- The control token needs no config key. It is generated on first use and persisted to `.git/gittally/control-token` (mode 600); operators can write their own token there, deleting the file rotates it. Requests pass it via the `X-GitTally-Token` header or a `token` parameter; mismatch answers 403 like legacy.
|
||||
- The control token needs no config key. It is generated on first use and persisted to `.git/werkator/control-token` (mode 600); operators can write their own token there, deleting the file rotates it. Requests pass it via the `X-werkator-Token` header or a `token` parameter; mismatch answers 403 like legacy.
|
||||
- `DELETE /api/builds/{artifactKey}` removes the result and then calls `ArtifactStore.prune(history)`, so no new store interface method was needed.
|
||||
- `GET /api/status/{commit}` also accepts abbreviated hashes (7–40 hex like legacy) and resolves them against the local history. The `GiteaClient` (step 03) gained 10s connect/read timeouts so the endpoint can never hang; a Gitea failure yields HTTP 200 with `status: unknown` (or the local status) plus `giteaError`.
|
||||
- `POST /api/builds/{branch}/restart` rebuilds the branch's last recorded commit. Branch names containing `/` would need an encoded slash, which Tomcat rejects by default — revisit in step 08 if the UI needs restart for such branches. (Resolved in step 08: the endpoint moved to `POST /api/builds/restart?branch=…`.)
|
||||
- Spring Boot 4 moved `@WebMvcTest` into the new `spring-boot-starter-webmvc-test` test module (added as test dependency).
|
||||
- The server-profile `@SpringBootTest` mocks the `Watcher` bean, so booting the test never fetches origin or enqueues builds; watcher wiring is proven by verifying `start()` was called.
|
||||
|
||||
Manual smoke test (2026-07-07): in a scratch repository, `java -jar build/libs/gittally-0.1.0-SNAPSHOT.jar server` started on the configured port 18981.
|
||||
Manual smoke test (2026-07-07): in a scratch repository, `java -jar build/libs/werkator-0.1.0-SNAPSHOT.jar server` started on the configured port 18981.
|
||||
`GET /api/builds/latest` answered `[]` with HTTP 200, `GET /api/watcher` exposed the failing fetch of the origin-less repo as `lastFetchError`, `GET /api/status/<sha>` answered `unknown` with HTTP 200, and cancel without token answered 403.
|
||||
SIGINT (Ctrl-C) shut the process down cleanly in about 2 seconds: port closed, no exceptions in the log, exit code 130.
|
||||
|
||||
@@ -48,7 +48,7 @@ Robust live updates (the actual bug fix):
|
||||
|
||||
## Implementation Notes (2026-07-07)
|
||||
|
||||
Implemented as designed: Thymeleaf templates (`fragments`, `builds`, `current`, `artifact`) rendered by `UiController`, one hand-written `static/gittally.js`, one `static/gittally.css` (loosely ported legacy look incl. dark mode and the mobile card layout), and the legacy favicon.
|
||||
Implemented as designed: Thymeleaf templates (`fragments`, `builds`, `current`, `artifact`) rendered by `UiController`, one hand-written `static/werkator.js`, one `static/werkator.css` (loosely ported legacy look incl. dark mode and the mobile card layout), and the legacy favicon.
|
||||
Pages render the full state server-side and work without JavaScript; the script polls the JSON API (tables 10s, current builds and log tails 3s) and re-renders table bodies from data.
|
||||
Every fetch runs with an 8s timeout; a failure flips the nav-row indicator to an explicit `error` badge and dims the stale table — there is no loading state at all, so no spinner can get stuck.
|
||||
Polling pauses on `visibilitychange` and refreshes immediately when the tab becomes visible; running durations tick client-side from `data-started-at`.
|
||||
@@ -57,7 +57,7 @@ Deviations and decisions:
|
||||
|
||||
- The tables show one `Started` column instead of the legacy `Commit Time` + `Status Time` pair, and client-side column sorting was not ported; the API delivers newest-first.
|
||||
- Status badges show the repository status; the per-row Gitea lookup (`/control/status` per commit) was deliberately not ported — that fan-out caused the legacy stuck spinners. `GET /api/status/{commit}` remains available.
|
||||
- The control token is embedded as a `<meta>` tag in every rendered page (legacy embedded its cancel token in the cancel form the same way); `gittally.js` sends it via `X-GitTally-Token` for restart/cancel/delete.
|
||||
- The control token is embedded as a `<meta>` tag in every rendered page (legacy embedded its cancel token in the cancel form the same way); `werkator.js` sends it via `X-werkator-Token` for restart/cancel/delete.
|
||||
- The restart endpoint moved from `POST /api/builds/{branch}/restart` to `POST /api/builds/restart?branch=…` so branch names with slashes work (resolves the step 07 deviation note).
|
||||
- Artifact links render whenever a result has an artifact key; the artifact index page itself explains a pruned/missing artifact directory instead of a per-row existence check.
|
||||
- `/builds/{artifactKey}` renders logs (top-level files) and the topmost `reports/**/index.html` pages from the artifact store; nested index pages below an already-listed one are skipped like legacy. Raw directory browsing is not offered.
|
||||
@@ -65,7 +65,7 @@ Deviations and decisions:
|
||||
- On `/current`, a build that leaves the running list keeps its card, marked `finished` with a link to its result page; its initial server render shows an empty log (the script fetches from offset 0).
|
||||
- JS builds all DOM via `createElement`/`textContent`, so re-rendered data cannot inject markup; server-side escaping is covered by a MockMvc test with a hostile branch name.
|
||||
- New config key `server.impressumUrl` (empty hides the footer link); the footer version comes from Spring Boot `buildInfo()` (`BuildProperties`, build time excluded for repeatability) with a `dev` fallback.
|
||||
- `UiFormats` (Kotlin) and `gittally.js` intentionally produce the same timestamp/duration display formats.
|
||||
- `UiFormats` (Kotlin) and `werkator.js` intentionally produce the same timestamp/duration display formats.
|
||||
|
||||
Manual smoke test (2026-07-07): scratch repository with a bare origin, `pollInterval: 5s`, and a 25s build command; server on port 18982, observed through a real browser tab.
|
||||
After `git push`, the open Latest tab showed the new build without reload and its badge flipped `running` → `success` live (`pending` was too short to sample; the row itself appeared via polling).
|
||||
@@ -81,9 +81,9 @@ Deviation: the listing enumerates origin branches instead of legacy's local bran
|
||||
Addendum (2026-07-07): the legacy per-page reload button (`⟳`, top right) was also re-added on request, next to the live indicator.
|
||||
On polling pages it triggers an immediate data refresh via the page's poller; pages without a poller (artifact index) reload fully.
|
||||
|
||||
Addendum (2026-07-07): all links that leave the GitTally UI open in a new tab (`target="_blank" rel="noopener noreferrer"`).
|
||||
Addendum (2026-07-07): all links that leave the Werkator UI open in a new tab (`target="_blank" rel="noopener noreferrer"`).
|
||||
This already held for Gitea branch/commit links and the footer; it was added for the artifact page's log and report links, whose targets have no navigation.
|
||||
Links between GitTally pages (nav, artifact index) stay in the same tab.
|
||||
Links between Werkator pages (nav, artifact index) stay in the same tab.
|
||||
|
||||
Addendum (2026-08-10): the artifacts column carries the whole build-reachability logic, and the nav lost its `Current` entry.
|
||||
The permanent `🔗` link is rendered on the build it resolves to — the branch's latest green build — on every build table, instead of on each row of a branch with any green build.
|
||||
|
||||
@@ -9,7 +9,7 @@ Port the legacy system page: CPU, RAM, disk, and repository size with min/max/av
|
||||
|
||||
## Design
|
||||
|
||||
Create package `de.hoennig.gittally.metrics`:
|
||||
Create package `de.hoennig.werkator.metrics`:
|
||||
|
||||
- `SystemMetricsCollector` sampling every 60s (server profile only):
|
||||
CPU used/idle from `/proc/stat` deltas, RAM from `/proc/meminfo`, disk from `java.nio.file.FileStore`, repo size via periodic `du -sk` (or a file walk) — throttle repo-size sampling (legacy ran `du` every cycle, which was expensive).
|
||||
@@ -36,10 +36,10 @@ Create package `de.hoennig.gittally.metrics`:
|
||||
|
||||
## Implementation Notes (2026-07-07)
|
||||
|
||||
Implemented as designed: `SystemMetricsCollector` in `de.hoennig.gittally.metrics` samples every 60s once `ServerMetricsLifecycle` (server profile only) calls `start()`, following the watcher's start/stop pattern.
|
||||
Implemented as designed: `SystemMetricsCollector` in `de.hoennig.werkator.metrics` samples every 60s once `ServerMetricsLifecycle` (server profile only) calls `start()`, following the watcher's start/stop pattern.
|
||||
CPU comes from `/proc/stat` deltas, RAM from `/proc/meminfo`, disk from `java.nio.file.FileStore` (`df` semantics: used = total − unallocated, free = usable), and the repository size from a file walk.
|
||||
`GET /api/system` returns the snapshot plus aggregates, and `/system` renders the legacy system page in the step 08 layout, polling every 60s with the same timeout/error-badge rules.
|
||||
Since the metric rows are fixed, `gittally.js` only updates the cell texts in place — nothing is rebuilt.
|
||||
Since the metric rows are fixed, `werkator.js` only updates the cell texts in place — nothing is rebuilt.
|
||||
|
||||
Deviations and decisions:
|
||||
|
||||
@@ -51,7 +51,7 @@ Deviations and decisions:
|
||||
- The repository size is re-probed only every 10th sample (10 minutes) and reused in between — the throttle this step requires; legacy ran `du -sk` every cycle.
|
||||
The file walk sums file sizes, not disk blocks like `du`, which is close enough for a trend metric.
|
||||
- An unavailable source (no `/proc` outside Linux, unreadable file store) yields explicit `null` metrics over HTTP 200 and `n/a` cells; the failure is logged once, not every 60s.
|
||||
- No new config keys: the 60s interval is fixed like legacy, so `GitTallyConfig`, the `init` templates, and `docs/configuration.md` are unchanged.
|
||||
- No new config keys: the 60s interval is fixed like legacy, so `WerkatorConfig`, the `init` templates, and `docs/configuration.md` are unchanged.
|
||||
- The legacy `generation` field was not ported; it only guarded the legacy JS against monitor restarts.
|
||||
- The CPU count comes from `Runtime.availableProcessors()` instead of `nproc`.
|
||||
|
||||
|
||||
@@ -39,7 +39,7 @@ Exit codes: 0 on success, 1 on build failure, 2 on usage/config errors (align wi
|
||||
|
||||
## Implementation Notes (2026-07-07)
|
||||
|
||||
Implemented as designed: `status`, `build`, and `retry` are picocli `@Component` subcommands in `commands/`, wired into `GitTallyCommand` like the existing ones.
|
||||
Implemented as designed: `status`, `build`, and `retry` are picocli `@Component` subcommands in `commands/`, wired into `WerkatorCommand` like the existing ones.
|
||||
They implement `Callable<Int>`, so the exit codes align with `CliRunner`'s `ExitCodeGenerator` contract: 0 on success, 1 on build failure, 2 on usage/config errors (picocli's own `USAGE` code for invalid options matches).
|
||||
|
||||
- `status [--history]` reads `BuildResultRepository` directly and prints an aligned table (branch, status, commit, time, duration); it reuses `UiFormats`, so the console shows the same timestamp/duration formats as the web UI.
|
||||
@@ -56,7 +56,7 @@ Deviations and decisions:
|
||||
- A failed fetch only warns and the commands continue from the last-known origin state, so they work offline.
|
||||
- `retry` only retries FAILED builds (legacy `branch_has_failed_build` checked exactly `failed`); interrupted/pending builds are the watcher's startup-recovery job.
|
||||
- Exit code 130 for cancelled builds was not ported; a cancelled/interrupted build exits 1 like any non-success.
|
||||
- Found while smoke testing: `.gitignore`'s `*.jar` rule excluded `gradle/wrapper/gradle-wrapper.jar`, so builds in fresh checkouts — including every GitTally worktree — failed with `ClassNotFoundException: GradleWrapperMain`.
|
||||
- Found while smoke testing: `.gitignore`'s `*.jar` rule excluded `gradle/wrapper/gradle-wrapper.jar`, so builds in fresh checkouts — including every Werkator worktree — failed with `ClassNotFoundException: GradleWrapperMain`.
|
||||
Fixed with a `!gradle/wrapper/gradle-wrapper.jar` exception and by adding the jar (same class of defect as the `build/` rule fixed in step 04).
|
||||
|
||||
Manual smoke test (2026-07-07, in this repository):
|
||||
|
||||
@@ -14,18 +14,18 @@ Implement a `DockerBuildRunner` for the `BuildRunner` interface from step 04, sh
|
||||
|
||||
Port from legacy (see analysis, lines ~4400+):
|
||||
|
||||
- Ensure image: build from configured Dockerfile/context when missing or stale; track staleness via an image label holding the SHA-256 of Dockerfile + context (legacy `org.gittally.build-inputs-sha256`).
|
||||
- Gradle cache volume per repository (`gittally-gradle-<repo-key>`), mounted and chowned to the host UID/GID.
|
||||
- Ensure image: build from configured Dockerfile/context when missing or stale; track staleness via an image label holding the SHA-256 of Dockerfile + context (legacy `org.werkator.build-inputs-sha256`).
|
||||
- Gradle cache volume per repository (`werkator-gradle-<repo-key>`), mounted and chowned to the host UID/GID.
|
||||
- Run the build container: workspace mount, branch env var, configured extra env, network mode, docker socket mount for Testcontainers-based builds.
|
||||
- Post-build ownership repair of the workspace (legacy `repair_docker_workspace_ownership`).
|
||||
- Label all containers (`org.hoennig.gittally=true`, repository, role) and clean up stale ones on startup.
|
||||
- Label all containers (`org.hoennig.werkator=true`, repository, role) and clean up stale ones on startup.
|
||||
|
||||
Decide during implementation whether the hsadmin-ng-specific legacy options (preflight command, `JAVA_TOOL_OPTIONS` injection) are needed; default to NOT porting them (see orphaned-config list in the analysis).
|
||||
|
||||
## Config
|
||||
|
||||
New `branches.<name>.docker` section: `enabled`, `image`, `dockerfile`, `context`, `network`, `env`.
|
||||
Update `GitTallyConfig`, `InitCommand` templates, and `docs/configuration.md` together.
|
||||
Update `WerkatorConfig`, `InitCommand` templates, and `docs/configuration.md` together.
|
||||
|
||||
## Tests
|
||||
|
||||
@@ -46,19 +46,19 @@ No test needs Docker; the main `docker run` argv is asserted exactly through an
|
||||
|
||||
Ported from legacy:
|
||||
|
||||
- Image ensure (`ensure_docker_build_image`): rebuild when the image is missing or the `org.gittally.build-inputs-sha256` label no longer matches; all four `org.gittally.*` labels are set.
|
||||
- Image ensure (`ensure_docker_build_image`): rebuild when the image is missing or the `org.werkator.build-inputs-sha256` label no longer matches; all four `org.werkator.*` labels are set.
|
||||
Without a configured `dockerfile`, the image is used as-is and pulled by `docker run` on demand.
|
||||
- Gradle cache volume `gittally-gradle-<repo-key>`, created and chowned to the host uid/gid with the legacy container script.
|
||||
- Gradle cache volume `werkator-gradle-<repo-key>`, created and chowned to the host uid/gid with the legacy container script.
|
||||
- Build container: workspace bind mount, `branch` env var, configured extra env, network mode, docker socket mount with `DOCKER_HOST`/`TESTCONTAINERS_*` for Testcontainers-based builds, `--add-host host.docker.internal:host-gateway` off host network.
|
||||
- Ownership repair of `build/` and `.gradle/` (`repair_docker_workspace_ownership`).
|
||||
- `org.hoennig.gittally` labels (role `build`) and stale-container cleanup.
|
||||
- `org.hoennig.werkator` labels (role `build`) and stale-container cleanup.
|
||||
|
||||
Deviations and decisions:
|
||||
|
||||
- The `BuildRunner` interface gained `repoDir` and `branchConfig` parameters (with defaults), because runner selection and Docker settings are per branch and the per-repo volume/container names need the repository path — a worktree cannot resolve the uncommitted config layer.
|
||||
- The hsadmin-ng-specific legacy options were not ported, as the step suggests: no preflight command, no `JAVA_TOOL_OPTIONS` injection, no `.testcontainers.properties` generation, no `HSADMINNG_*` env passthrough — `TESTCONTAINERS_DOCKER_SOCKET_OVERRIDE`/`TESTCONTAINERS_HOST_OVERRIDE`/`DOCKER_HOST` cover modern Testcontainers; anything else fits `docker.env`.
|
||||
- Ownership repair runs inside the same build container (wrapped around the command, preserving its exit code) instead of a follow-up root container; the separate `prepare_docker_workspace_build_dir` step became unnecessary because the clean command already runs in the container.
|
||||
- Container names are per branch (`gittally-build-<repo-key>-<branch-key>`), not per repository, because builds of different branches may run concurrently.
|
||||
- Container names are per branch (`werkator-build-<repo-key>-<branch-key>`), not per repository, because builds of different branches may run concurrently.
|
||||
- Containers run with `--init`, so termination signals from build cancellation reach the build process inside the container.
|
||||
- Stale labelled containers are removed before the first Docker build of the process, not at daemon startup, so installations that never build in Docker never invoke docker.
|
||||
- The Gradle volume is prepared once per process and image, not before every build.
|
||||
@@ -68,8 +68,8 @@ Deviations and decisions:
|
||||
|
||||
Manual smoke test (2026-07-07, scratch repo, Rancher Desktop 27.3.1):
|
||||
|
||||
- A scratch repo with `docker.enabled`, a two-line Dockerfile, and a build command writing `id -u` into `build/who.txt`: `gittally build` built the image with all four labels, created the `gittally-gradle-<repo-key>` volume, streamed the container output live, and exited 0 (`success after 0:14`).
|
||||
- A scratch repo with `docker.enabled`, a two-line Dockerfile, and a build command writing `id -u` into `build/who.txt`: `werkator build` built the image with all four labels, created the `werkator-gradle-<repo-key>` volume, streamed the container output live, and exited 0 (`success after 0:14`).
|
||||
- A second run reused the image (inputs label matched, no rebuild; `success after 0:04`).
|
||||
- The command ran as uid 0 inside the container while `build/who.txt` ended up owned by the host user — the in-container ownership repair works.
|
||||
- No labelled containers were left behind after the builds.
|
||||
- Caveat found while testing (environmental, not GitTally): with a VM-based Docker (Rancher Desktop/Lima), workspace bind mounts only work for paths shared into the VM (e.g. `$HOME`); a repo under an unshared `/tmp` builds against an empty VM-side directory.
|
||||
- Caveat found while testing (environmental, not Werkator): with a VM-based Docker (Rancher Desktop/Lima), workspace bind mounts only work for paths shared into the VM (e.g. `$HOME`); a repo under an unshared `/tmp` builds against an empty VM-side directory.
|
||||
|
||||
+12
-11
@@ -5,13 +5,13 @@ Read `README.md` and `00-legacy-analysis.md` first.
|
||||
|
||||
## Goal
|
||||
|
||||
Make the new GitTally deployable as a service and retire the legacy script.
|
||||
Make the new Werkator deployable as a service and retire the legacy script.
|
||||
|
||||
## Design
|
||||
|
||||
Deployment (documentation plus a small generator, no self-install):
|
||||
|
||||
- Extend `init` (or add `init --systemd`) to generate a systemd user unit running `java -jar gittally.jar server` with `WorkingDirectory` set to the repo, `Restart=always`, and an `EnvironmentFile` for overrides — port the shape of the legacy unit, drop the self-copy/update machinery.
|
||||
- Extend `init` (or add `init --systemd`) to generate a systemd user unit running `java -jar werkator.jar server` with `WorkingDirectory` set to the repo, `Restart=always`, and an `EnvironmentFile` for overrides — port the shape of the legacy unit, drop the self-copy/update machinery.
|
||||
- Write `docs/deployment.md`: JRE requirement, jar location convention, systemd enable/start/log commands, and reverse-proxy guidance (example nginx `server` block proxying to `server.port`; TLS via the host's existing certbot — replaces the legacy managed nginx container).
|
||||
|
||||
Migration:
|
||||
@@ -21,8 +21,8 @@ Migration:
|
||||
|
||||
Housekeeping:
|
||||
|
||||
- Mark `legacy/gitTally` as deprecated in its header comment and in `README.md`.
|
||||
- Review `docs/GitTally-Konzept.md` against what was actually built; update or note deviations.
|
||||
- Mark `legacy/werkator` as deprecated in its header comment and in `README.md`.
|
||||
- Review `../Werkator-Konzept.md` against what was actually built; update or note deviations.
|
||||
- Add an ADR summarizing the architecture decisions that emerged during the rewrite (persistence choice, polling UI, no nginx management).
|
||||
|
||||
## Tests
|
||||
@@ -37,25 +37,26 @@ Housekeeping:
|
||||
|
||||
## Implementation Notes (2026-07-07)
|
||||
|
||||
Implemented as designed: `init --systemd` (an option on `init`, not a separate subcommand) generates the unit and its `EnvironmentFile` under `.git/gittally/`, prints the install commands, and never touches `~/.config/systemd` itself (no self-install).
|
||||
Implemented as designed: `init --systemd` (an option on `init`, not a separate subcommand) generates the unit and its `EnvironmentFile` under `.git/werkator/`, prints the install commands, and never touches `~/.config/systemd` itself (no self-install).
|
||||
`SystemdServiceFiles` builds the file contents and is unit-tested by content assertions, including the legacy `%` escaping and `ExecStart` quoting.
|
||||
`docs/deployment.md` and `docs/migration-from-legacy.md` were written; `README.md`, `docs/bootstrapping.md`, `docs/GitTally-Konzept.md`, and `CLAUDE.md` were updated to reference them.
|
||||
`docs/deployment.md` and `docs/migration-from-legacy.md` were written; `README.md`, `docs/bootstrapping.md`, `../Werkator-Konzept.md`, and `CLAUDE.md` were updated to reference them.
|
||||
`docs/migration-from-legacy.md` was deleted again on 2026-08-30 with the rename to Werkator: every host it addressed had long since moved to the YAML configuration.
|
||||
|
||||
Deviations and decisions:
|
||||
|
||||
- The unit is named per repository (`gittally-<repo-name>.service`) instead of the global legacy `gitTally.service`, because one instance serves one repository and several repositories can share a host.
|
||||
- The unit is named per repository (`werkator-<repo-name>.service`) instead of the global legacy `werkator.service`, because one instance serves one repository and several repositories can share a host.
|
||||
- `ExecStart` uses the `java` binary and the jar path of the JVM that ran `init --systemd`, so the unit points at the jar in place (legacy copied the script to an install dir); systemd expands `$JAVA_OPTS` from the `EnvironmentFile` into the command line.
|
||||
When not started via `java -jar` (e.g. from Gradle), `init --systemd` prints an error instead of generating a broken unit.
|
||||
- The `EnvironmentFile` only tunes the JVM (`JAVA_OPTS`); the legacy env file carried username/token, which now live in `.git/gittally/.gittally.yml`.
|
||||
An existing `gittally.env` is kept; the unit file is regenerated on every run (same as legacy).
|
||||
- The `EnvironmentFile` only tunes the JVM (`JAVA_OPTS`); the legacy env file carried username/token, which now live in `.git/werkator/.werkator.yml`.
|
||||
An existing `werkator.env` is kept; the unit file is regenerated on every run (same as legacy).
|
||||
- The legacy `--nginx --docker` `ExecStart` flags were dropped (runtime selection is per-branch config now); the `After=… docker.service` ordering was kept.
|
||||
- Legacy build history (`build-results.tsv`) is not imported — decided and documented in `docs/migration-from-legacy.md` (formats differ substantially; retention would prune imported rows quickly).
|
||||
- ADR 0004 records the rewrite architecture decisions (JSON-file persistence behind a repository interface, polling UI, no managed nginx).
|
||||
- `docs/GitTally-Konzept.md` review: only one real deviation found — "Builds laufen in Docker" became "nativ oder optional in Docker (pro Branch konfigurierbar)"; CLI capability lists gained build/retry; deployment links added.
|
||||
- `../Werkator-Konzept.md` review: only one real deviation found — "Builds laufen in Docker" became "nativ oder optional in Docker (pro Branch konfigurierbar)"; CLI capability lists gained build/retry; deployment links added.
|
||||
|
||||
Manual walkthrough (2026-07-07, fresh clone under `~/.cache`):
|
||||
|
||||
- Followed `docs/deployment.md` end to end: built the jar, copied it to a stable path, cloned the repository freshly, ran `init` and `init --systemd`, linked the generated unit, `daemon-reload`, started the service.
|
||||
- The clone already contained the committed `.gittally.yml`, so only the machine config was created; `server.port` was overridden to a free port via `.git/gittally/.gittally.yml` to avoid clashing with a locally running instance.
|
||||
- The clone already contained the committed `.werkator.yml`, so only the machine config was created; `server.port` was overridden to a free port via `.git/werkator/.werkator.yml` to avoid clashing with a locally running instance.
|
||||
- Result: unit `active (running)`, `GET /` returned 200, `/api/watcher` showed a successful poll, `journalctl --user -u …` showed the startup log, `restart` and `stop` worked; the unit link and the scratch clone were removed afterwards.
|
||||
- Not machine-verified: `systemctl --user enable` and `loginctl enable-linger` (the walkthrough used a transient `start` to leave no persistent service behind) and the nginx/certbot section (no public host available); those commands were reviewed against the systemd/certbot documentation instead.
|
||||
|
||||
@@ -2,22 +2,22 @@
|
||||
|
||||
Prerequisites: steps 07, 11, 12.
|
||||
Read `README.md`, `00-legacy-analysis.md`, and ADR 0005 first.
|
||||
Consult `legacy/gitTally` for the functions referenced below.
|
||||
Consult `legacy/werkator` for the functions referenced below.
|
||||
|
||||
## Goal
|
||||
|
||||
Serve GitTally over HTTPS on hosts that provide Docker but no host reverse proxy (e.g. Hostsharing managed container environments).
|
||||
GitTally optionally manages an nginx Docker container with Let's Encrypt certificates, ported from the legacy subsystem.
|
||||
Serve Werkator over HTTPS on hosts that provide Docker but no host reverse proxy (e.g. Hostsharing managed container environments).
|
||||
Werkator optionally manages an nginx Docker container with Let's Encrypt certificates, ported from the legacy subsystem.
|
||||
This is opt-in; the reverse-proxy deployment from step 12 stays the default (ADR 0005).
|
||||
|
||||
## Design
|
||||
|
||||
Port the legacy nginx subsystem (functions `configure_artifact_nginx_defaults` ~1545, `artifact_nginx_write_ssl_options` ~4051, `artifact_nginx_write_config` ~4077, `artifact_nginx_ports_free` ~4242, `cleanup_stale_artifact_nginx_containers` ~4274, `artifact_nginx_run_container` ~4281, `artifact_nginx_obtain_or_renew_certificate` ~4310, `start_artifact_nginx` ~4342, shutdown cleanup ~723):
|
||||
|
||||
- Config under `server.nginx.*`: `enabled` (default false), `serverName`, `httpPort` (8080), `httpsPort` (8443), `upstreamHost` (default: `serverName`), `containerName` (default: `gittally-nginx-<repo-name>`), `stateDir` (default: `${XDG_STATE_HOME:-~/.local/state}/gittally/nginx/<repoKey>`), `letsencryptEmail`.
|
||||
Update all three config places (`GitTallyConfig`, `init` templates, `docs/configuration.md`).
|
||||
- Config under `server.nginx.*`: `enabled` (default false), `serverName`, `httpPort` (8080), `httpsPort` (8443), `upstreamHost` (default: `serverName`), `containerName` (default: `werkator-nginx-<repo-name>`), `stateDir` (default: `${XDG_STATE_HOME:-~/.local/state}/werkator/nginx/<repoKey>`), `letsencryptEmail`.
|
||||
Update all three config places (`WerkatorConfig`, `init` templates, `docs/configuration.md`).
|
||||
- When `server.publicBaseUrl` is empty and `serverName` is set, default it to `https://<serverName>/` (legacy line ~541).
|
||||
- Shell out to the `docker` CLI like `DockerBuildRunner` (no SDK); label the container `org.hoennig.gittally` for stale-container cleanup.
|
||||
- Shell out to the `docker` CLI like `DockerBuildRunner` (no SDK); label the container `org.hoennig.werkator` for stale-container cleanup.
|
||||
- Lifecycle as a server-profile component (like `ServerWatcherLifecycle`/`ServerMetricsLifecycle`): start after the web server is up, stop and remove the container on shutdown.
|
||||
Nothing runs in CLI mode or tests.
|
||||
- Two-phase startup, ported from legacy: write an HTTP-only nginx config for the ACME webroot challenge, run the container, obtain the certificate via a certbot container (webroot mode), then rewrite the full HTTPS config and restart nginx.
|
||||
@@ -36,7 +36,7 @@ Port the legacy nginx subsystem (functions `configure_artifact_nginx_defaults` ~
|
||||
|
||||
- `./gradlew ktlintFormat` then `./gradlew build` is green.
|
||||
- With `server.nginx.enabled: false` (default) nothing changes; no container is touched.
|
||||
- Manual walkthrough on a Docker host: nginx container starts with the init config and proxies HTTP to GitTally.
|
||||
- Manual walkthrough on a Docker host: nginx container starts with the init config and proxies HTTP to werkator.
|
||||
Full ACME issuance needs a public DNS name; if none is available, verify the certbot argv and the full-config path against the legacy script and document that in this file.
|
||||
- `docs/deployment.md` gains a section for hosts without a reverse proxy; `docs/migration-from-legacy.md` maps the `GITTALLY_ARTIFACT_NGINX_*`/`GITTALLY_ARTIFACT_LETSENCRYPT_EMAIL` variables.
|
||||
|
||||
@@ -50,7 +50,7 @@ Deviations from the design above and from legacy:
|
||||
- Legacy auto-moved the artifact server port on a collision with the nginx ports; the rewrite refuses to start the proxy with a warning instead — the Spring port cannot move after startup.
|
||||
- Legacy derived a missing `serverName` from the public base URL host; the rewrite requires `serverName` explicitly (the config default direction is only publicBaseUrl ← serverName).
|
||||
- `serverName` and `upstreamHost` are validated against a host-name pattern instead of substituting raw values, so no nginx directives can be injected via config.
|
||||
- The container label namespace is `org.hoennig.gittally` (like the Docker build runner), not `org.hostsharing.gittally`; port cleanup still also matches legacy-named containers.
|
||||
- The container label namespace is `org.hoennig.werkator` (like the Docker build runner), not `org.hostsharing.werkator`; port cleanup still also matches legacy-named containers.
|
||||
- The legacy `--nginx` CLI flag is not ported; enablement is `server.nginx.enabled` only.
|
||||
- `ssl-dhparams.pem` is downloaded via the Java HTTP client instead of `curl` (replaceable seam for tests).
|
||||
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
# Step 14: Build-Phase Timing and Orchestration Overhead
|
||||
|
||||
Prerequisites: steps 04 (build executor), 05 (artifact store), 07 (API), 08 (web UI), 11 (Docker runtime).
|
||||
Read `README.md` first; read the referenced `legacy/gitTally` functions only where this step points at them.
|
||||
Read `README.md` first; read the referenced legacy functions only where this step points at them — the script lives in the history now, see `README.md`.
|
||||
|
||||
## Goal
|
||||
|
||||
|
||||
@@ -6,8 +6,8 @@ This step revises the "Future: Docker-based Deployment" section of `docs/bootstr
|
||||
|
||||
## Goal
|
||||
|
||||
Deploy GitTally on hosts that provide Docker and git but no Java runtime (Hostsharing container servers, e.g. `tallyman@vm4006`).
|
||||
GitTally is distributed as a self-contained runtime bundle: a jlink-trimmed JRE plus `gittally.jar` plus a launcher script, packed as one tarball.
|
||||
Deploy Werkator on hosts that provide Docker and git but no Java runtime (Hostsharing container servers, e.g. `tallyman@vm4006`).
|
||||
Werkator is distributed as a self-contained runtime bundle: a jlink-trimmed JRE plus `werkator.jar` plus a launcher script, packed as one tarball.
|
||||
The JAR stays the primary artifact for development and for hosts that already have a JRE.
|
||||
|
||||
## Distribution Format Decision (ADR 0006)
|
||||
@@ -17,9 +17,9 @@ Three formats were considered; write ADR 0006 recording the decision and this ra
|
||||
- **jlink runtime bundle (chosen)** — no production-code changes, plain JVM semantics, one tarball to `scp`.
|
||||
git and docker CLIs are used from the host, worktree paths stay host paths, and the `init --systemd` unit works unchanged because `java.home` and the running-jar path resolve into the bundle.
|
||||
- **GraalVM native image (rejected)** — Spring AOT evaluates bean conditions at build time.
|
||||
GitTally's dual-context design (CLI context without web, second `SpringApplication` with the `server` profile and `WebApplicationType.SERVLET`, `@Profile("!server")` `CliRunner`, `@Profile("server")` lifecycles) cannot be represented in a single AOT arrangement.
|
||||
Werkator's dual-context design (CLI context without web, second `SpringApplication` with the `server` profile and `WebApplicationType.SERVLET`, `@Profile("!server")` `CliRunner`, `@Profile("server")` lifecycles) cannot be represented in a single AOT arrangement.
|
||||
Supporting it would require replacing the profile wiring with runtime guards and collapsing the two context shapes — an invasive rewrite with regression risk for the JVM path.
|
||||
- **Containerized GitTally runtime (rejected, was the `docs/bootstrapping.md` sketch)** — needs git and docker CLIs inside the image, a same-path `$HOME` mount plus docker-socket mount and uid/gid mapping so that `DockerBuildRunner`'s `--volume $workspace:$workspace` sibling mounts keep working, and a hand-edited systemd unit.
|
||||
- **Containerized Werkator runtime (rejected, was the `docs/bootstrapping.md` sketch)** — needs git and docker CLIs inside the image, a same-path `$HOME` mount plus docker-socket mount and uid/gid mapping so that `DockerBuildRunner`'s `--volume $workspace:$workspace` sibling mounts keep working, and a hand-edited systemd unit.
|
||||
Kept as the documented fallback if the bundle approach ever becomes unworkable.
|
||||
|
||||
## Target Host Facts (verified 2026-08-10)
|
||||
@@ -35,15 +35,15 @@ Gradle:
|
||||
- Add a `runtimeBundle` task (depends on `bootJar`); the normal `./gradlew build` stays unchanged.
|
||||
- The task runs `jlink` from the configured Java toolchain (every JDK 21 ships jlink; no new toolchain requirement).
|
||||
- The JDK module list is pinned in the build script, computed once via `jdeps` on the exploded boot jar and its `BOOT-INF/lib`; document the jdeps command next to the list and re-check it when dependencies change.
|
||||
- Bundle layout: `gittally/jre/` (jlink image), `gittally/lib/gittally.jar`, `gittally/bin/gittally` (sh launcher: `exec "$DIR/../jre/bin/java" $JAVA_OPTS -jar "$DIR/../lib/gittally.jar" "$@"`).
|
||||
- Output: `build/distributions/gittally-runtime-linux-x64.tar.gz` with preserved execute permissions.
|
||||
- Bundle layout: `werkator/jre/` (jlink image), `werkator/lib/werkator.jar`, `werkator/bin/werkator` (sh launcher: `exec "$DIR/../jre/bin/java" $JAVA_OPTS -jar "$DIR/../lib/werkator.jar" "$@"`).
|
||||
- Output: `build/distributions/werkator-runtime-linux-x64.tar.gz` with preserved execute permissions.
|
||||
|
||||
Deployment (no code changes expected):
|
||||
|
||||
- Unpack to `~/opt/gittally/` on the target host; run everything via `~/opt/gittally/bin/gittally`.
|
||||
- `init --systemd` already generates `ExecStart=<java> $JAVA_OPTS -jar <jar> server` from `java.home` and the running jar path — from the bundle both resolve into `~/opt/gittally/`, so the unit points at the bundle without changes.
|
||||
- Unpack to `~/opt/werkator/` on the target host; run everything via `~/opt/werkator/bin/werkator`.
|
||||
- `init --systemd` already generates `ExecStart=<java> $JAVA_OPTS -jar <jar> server` from `java.home` and the running jar path — from the bundle both resolve into `~/opt/werkator/`, so the unit points at the bundle without changes.
|
||||
Verify this instead of adapting code; adapt only if the resolution fails.
|
||||
- Updating GitTally = unpack a new bundle over `~/opt/gittally/` (or switch a symlink) and restart the service.
|
||||
- Updating Werkator = unpack a new bundle over `~/opt/werkator/` (or switch a symlink) and restart the service.
|
||||
|
||||
Documentation:
|
||||
|
||||
@@ -55,13 +55,13 @@ Documentation:
|
||||
## Tests
|
||||
|
||||
- No production code changes are expected, so no new unit tests; existing tests must stay green.
|
||||
- Smoke-verify the bundle manually: `bin/gittally --help`, `init` in a scratch repo, `config:print --full`, a short `server` run, and `init --systemd` unit content pointing into the bundle; document the results in this file.
|
||||
- Verify on vm4006 (which has no Java): copy the bundle, run `bin/gittally --help` and `config:print`; document the results in this file.
|
||||
- Smoke-verify the bundle manually: `bin/werkator --help`, `init` in a scratch repo, `config:print --full`, a short `server` run, and `init --systemd` unit content pointing into the bundle; document the results in this file.
|
||||
- Verify on vm4006 (which has no Java): copy the bundle, run `bin/werkator --help` and `config:print`; document the results in this file.
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- `./gradlew ktlintFormat` then `./gradlew build` is green, with unchanged toolchain requirements.
|
||||
- `./gradlew runtimeBundle` produces a tarball whose `bin/gittally` runs `--help`, `init`, and `server` on a machine without any Java runtime.
|
||||
- `./gradlew runtimeBundle` produces a tarball whose `bin/werkator` runs `--help`, `init`, and `server` on a machine without any Java runtime.
|
||||
- A fresh deployment to vm4006 following `docs/deployment.md` and `docs/migration-from-legacy.md` reaches a running service: web UI reachable, a Docker build succeeds, commit status arrives in Gitea, managed nginx/TLS works (`server.nginx.enabled: true`, DNS for `serverName` pointing at vm4006).
|
||||
- vm2176 (legacy) keeps running in parallel during the migration; the legacy service is only retired after vm4006 is verified.
|
||||
- Docs and ADR 0006 written as described; document deviations in this file.
|
||||
@@ -71,15 +71,15 @@ Documentation:
|
||||
Implemented as designed; no production-code change was needed.
|
||||
The step was originally drafted for a GraalVM native image; it was re-planned to the jlink bundle after the Spring-AOT build-time condition evaluation turned out to be incompatible with the dual-context CLI/server wiring (see ADR 0006).
|
||||
|
||||
- `runtimeBundle` task in `build.gradle.kts` with the pinned module list (jdeps output plus java.logging, jdk.crypto.ec, jdk.management, jdk.zipfs); launcher script in `packaging/gittally`; tarball ~66 MB.
|
||||
- `runtimeBundle` task in `build.gradle.kts` with the pinned module list (jdeps output plus java.logging, jdk.crypto.ec, jdk.management, jdk.zipfs); launcher script in `packaging/werkator`; tarball ~66 MB.
|
||||
- Smoke tests on the dev machine (with `JAVA_HOME` unset and a stripped `PATH`): `--help`, `init --systemd` in a scratch repo, `config:print --full`, and a `server` run all passed; `/` served HTTP 200 and `/api/branches` returned JSON.
|
||||
- The `init --systemd` unit generated from the bundle points at `<bundle>/jre/bin/java` and `<bundle>/lib/gittally.jar` as predicted — no detection code needed.
|
||||
- Verified on vm4006 (no Java installed): bundle unpacked to `~/opt/gittally`, `--version`, `--help`, and `status` in a scratch repo (host git via `GitCommandRunner`) all worked.
|
||||
- The `init --systemd` unit generated from the bundle points at `<bundle>/jre/bin/java` and `<bundle>/lib/werkator.jar` as predicted — no detection code needed.
|
||||
- Verified on vm4006 (no Java installed): bundle unpacked to `~/opt/werkator`, `--version`, `--help`, and `status` in a scratch repo (host git via `GitCommandRunner`) all worked.
|
||||
|
||||
Production deployment to vm4006 (2026-08-10, same session):
|
||||
|
||||
- `hs.hsadmin.ng` cloned to `~/hs.hsadmin.ng` on vm4006; legacy configuration from vm2176 (repo `.gitTally` + `gitTally.env`) migrated to `.gittally.yml` per `docs/migration-from-legacy.md`; Gitea token moved (the token in vm2176's `gitTally.env` file was stale — the valid one came from the running legacy process environment).
|
||||
- `statusContext: GitTally@vm4006` for the parallel phase; rename to `GitTally` after vm2176 is retired.
|
||||
- `hs.hsadmin.ng` cloned to `~/hs.hsadmin.ng` on vm4006; legacy configuration from vm2176 (repo `.werkator` + `werkator.env`) migrated to `.werkator.yml` per `docs/migration-from-legacy.md`; Gitea token moved (the token in vm2176's `werkator.env` file was stale — the valid one came from the running legacy process environment).
|
||||
- `statusContext: werkator@vm4006` for the parallel phase; rename to `werkator` after vm2176 is retired.
|
||||
- systemd user service installed via `init --systemd` from the bundle and running; watcher fetches origin branches with the migrated credentials.
|
||||
- Managed nginx/TLS live: Let's Encrypt certificate for `vm4006.hostsharing.net` obtained, `https://vm4006.hostsharing.net/` serves the UI with a valid chain, HTTP 301s to HTTPS (Hostsharing routes public 80/443 to `httpPort`/`httpsPort`, same as on vm2176).
|
||||
- Fix discovered during rollout: certbot removed `ssl-dhparams.pem` from its repository, so the first nginx start failed with HTTP 404.
|
||||
@@ -99,83 +99,89 @@ Fix: `HSADMINNG_POSTGRES_ADMIN_USERNAME=admin` and `HSADMINNG_POSTGRES_RESTRICTE
|
||||
Verified by running both test classes in the build container with the variables set: green.
|
||||
Open oddity: the same commit passed on vm2176 although neither its daemon environment, build image, Gradle volume, nor any build-script mechanism supplies these variables there (an unused git-ignored `.environment` file exists in its primary checkout, but nothing in the build reads it); the loading path on vm2176 remains unidentified.
|
||||
|
||||
Fourth finding (GitTally limitation, worked around in config): with all tests green, the build then failed in hsadmin-ng's `:prQuickCheck` — "fatal: not a git repository".
|
||||
GitTally builds in a git worktree whose `.git` is a pointer file into the primary repository's `.git/worktrees/…`, and the Docker build container (deliberately, credentials live under `.git/gittally/`) only mounts the worktree — so build steps that call git fail; the legacy script avoided this by building in the primary checkout.
|
||||
Fourth finding (Werkator limitation, worked around in config): with all tests green, the build then failed in hsadmin-ng's `:prQuickCheck` — "fatal: not a git repository".
|
||||
Werkator builds in a git worktree whose `.git` is a pointer file into the primary repository's `.git/worktrees/…`, and the Docker build container (deliberately, credentials live under `.git/werkator/`) only mounts the worktree — so build steps that call git fail; the legacy script avoided this by building in the primary checkout.
|
||||
Workaround: `prQuickCheck` removed from the vm4006 build command — it is a PR quality gate against a base branch and has no meaning in a post-merge master build (on vm2176 it only passed as an accidental no-op).
|
||||
The underlying question (safe git availability inside Docker build containers without exposing `.git/gittally/` secrets) is left as a follow-up design task.
|
||||
The underlying question (safe git availability inside Docker build containers without exposing `.git/werkator/` secrets) is left as a follow-up design task.
|
||||
|
||||
Cutover completed (2026-08-10, same day): after three green master builds and verified Gitea statuses from vm4006, the legacy service on vm2176 was disabled and removed from systemd.
|
||||
vm4006's `statusContext` was switched to the canonical `GitTally` (effective without a restart — the Gitea client loads the config per call), and the branches still carrying red statuses from the buggy first hours were re-queued.
|
||||
vm2176 now runs only a redirect nginx container (`gittally-redirect`, ports 8080/8443 like before): HTTP and HTTPS answer 301 to `https://vm4006.hostsharing.net$request_uri`, the ACME webroot keeps serving so the `nginx-letsencrypt-renew.timer` continues to renew the old host's certificate (the renew unit gained an `ExecStartPost` nginx reload).
|
||||
GitTally answers the legacy static page names (`/index.html`, `/branches.html`, `/history.html`, `/system.html`, `/about.html`, `/license.html`) with permanent redirects to the new routes, so pre-rewrite links survive the host redirect.
|
||||
vm4006's `statusContext` was switched to the canonical `werkator` (effective without a restart — the Gitea client loads the config per call), and the branches still carrying red statuses from the buggy first hours were re-queued.
|
||||
vm2176 now runs only a redirect nginx container (`werkator-redirect`, ports 8080/8443 like before): HTTP and HTTPS answer 301 to `https://vm4006.hostsharing.net$request_uri`, the ACME webroot keeps serving so the `nginx-letsencrypt-renew.timer` continues to renew the old host's certificate (the renew unit gained an `ExecStartPost` nginx reload).
|
||||
Werkator answers the legacy static page names (`/index.html`, `/branches.html`, `/history.html`, `/system.html`, `/about.html`, `/license.html`) with permanent redirects to the new routes, so pre-rewrite links survive the host redirect.
|
||||
|
||||
Update to v0.9.8 (2026-08-10): the running build was awaited first (a restart would have killed it), then service stopped, `~/opt/gittally` backed up to `~/opt/gittally.v0.9.7.bak` and the new bundle unpacked over it, service started.
|
||||
Update to v0.9.8 (2026-08-10): the running build was awaited first (a restart would have killed it), then service stopped, `~/opt/werkator` backed up to `~/opt/werkator.v0.9.7.bak` and the new bundle unpacked over it, service started.
|
||||
Verified live: `/` reports v0.9.8, the nav has no `Current` entry, the permanent `🔗` link appears only on branches whose latest build is their latest green one, and the newly linked reports answer 200 — including the stable `/branches/<branch>/reports/profile/`.
|
||||
Master has no profile report yet because its `.gittally.yml` still carries the pre-PR#282 build command; it appears once that PR merges.
|
||||
Master has no profile report yet because its `.werkator.yml` still carries the pre-PR#282 build command; it appears once that PR merges.
|
||||
|
||||
Update to v0.9.9 (2026-08-11): no build was running, service stopped, `~/opt/gittally` backed up to `~/opt/gittally.v0.9.8.bak` and replaced by the new bundle, service started.
|
||||
The changed `server.bindAddress` default was harmless here because vm4006 sets `0.0.0.0` explicitly in `.git/gittally/.gittally.yml` — which the managed nginx container needs.
|
||||
Found and fixed on the host: `.git/gittally/.gittally.yml` (the Gitea token) was still `0644` and its directory `0755` from the pre-0.9.9 `init`; both were tightened to `0600`/`0700` manually, as the new code only sets the mode for files it creates.
|
||||
Update to v0.9.9 (2026-08-11): no build was running, service stopped, `~/opt/werkator` backed up to `~/opt/werkator.v0.9.8.bak` and replaced by the new bundle, service started.
|
||||
The changed `server.bindAddress` default was harmless here because vm4006 sets `0.0.0.0` explicitly in `.git/werkator/.werkator.yml` — which the managed nginx container needs.
|
||||
Found and fixed on the host: `.git/werkator/.werkator.yml` (the Gitea token) was still `0644` and its directory `0755` from the pre-0.9.9 `init`; both were tightened to `0600`/`0700` manually, as the new code only sets the mode for files it creates.
|
||||
Verified live: `/` reports v0.9.9, HTTP 301s to HTTPS with a valid certificate, `/api/builds/latest` answers, a control token in the query string is rejected with 403, `config:print` masks `git.token`, and the mobile header stacks title over repository name.
|
||||
|
||||
Update to v0.9.10 (2026-08-11): same procedure, `~/opt/gittally.v0.9.9.bak` as the rollback copy.
|
||||
Verified live: `/` reports v0.9.10, the pages no longer contain `gittally-control-token`, `/api/builds/latest` and `/branches` still answer 200 without any credential, and a mutation without the token is rejected with 403.
|
||||
The operator has to paste the token from `~/hs.hsadmin.ng/.git/gittally/control-token` once per browser now.
|
||||
Update to v0.9.10 (2026-08-11): same procedure, `~/opt/werkator.v0.9.9.bak` as the rollback copy.
|
||||
Verified live: `/` reports v0.9.10, the pages no longer contain `werkator-control-token`, `/api/builds/latest` and `/branches` still answer 200 without any credential, and a mutation without the token is rejected with 403.
|
||||
The operator has to paste the token from `~/hs.hsadmin.ng/.git/werkator/control-token` once per browser now.
|
||||
|
||||
Update to v0.9.11 (2026-08-14): same procedure, no build was running, `~/opt/gittally.0.9.10.bak` as the rollback copy.
|
||||
Verified live: `bin/gittally --version` reports v0.9.11 before the start, the service is `active`, `/` answers 200 with v0.9.11 in the footer, `/releases` shows the v0.9.11 entry, and `/api/builds/current` is empty.
|
||||
Update to v0.9.11 (2026-08-14): same procedure, no build was running, `~/opt/werkator.0.9.10.bak` as the rollback copy.
|
||||
Verified live: `bin/werkator --version` reports v0.9.11 before the start, the service is `active`, `/` answers 200 with v0.9.11 in the footer, `/releases` shows the v0.9.11 entry, and `/api/builds/current` is empty.
|
||||
The watcher's new local-ref fast-forward logged nothing, because `~/hs.hsadmin.ng` had already been reset to `origin/master` by hand — it only acts on a branch that actually lags behind.
|
||||
|
||||
Update to v0.9.12 (2026-08-26): same procedure, `~/opt/gittally.0.9.11.bak` as the rollback copy; a build was running — interrupted and re-enqueued by the startup recovery as designed.
|
||||
Verified live: `bin/gittally --version` reports v0.9.12 before the start, the service is `active`, `/` shows v0.9.12, and the recovery re-enqueued exactly one build per affected branch (the pre-fix duplicate queue entries were collapsed by `markStaleRunningAsInterrupted` + `latestPerBranch`).
|
||||
Update to v0.9.12 (2026-08-26): same procedure, `~/opt/werkator.0.9.11.bak` as the rollback copy; a build was running — interrupted and re-enqueued by the startup recovery as designed.
|
||||
Verified live: `bin/werkator --version` reports v0.9.12 before the start, the service is `active`, `/` shows v0.9.12, and the recovery re-enqueued exactly one build per affected branch (the pre-fix duplicate queue entries were collapsed by `markStaleRunningAsInterrupted` + `latestPerBranch`).
|
||||
Shipped fixes: prune never removes queued/running results (a branch deleted mid-build stays visible), and manual triggers dedup against an already active build of the same branch and commit.
|
||||
|
||||
Update to v0.9.13 (2026-08-28): same procedure, no build was running, `~/opt/gittally.0.9.12.bak` as the rollback copy.
|
||||
Verified live: `bin/gittally --version` reports v0.9.13 before the start, the service is `active`, `/` answers 200 with v0.9.13 in the footer, `/api/builds/latest` carries the new `name` field, and the watcher polls without errors.
|
||||
Update to v0.9.13 (2026-08-28): same procedure, no build was running, `~/opt/werkator.0.9.12.bak` as the rollback copy.
|
||||
Verified live: `bin/werkator --version` reports v0.9.13 before the start, the service is `active`, `/` answers 200 with v0.9.13 in the footer, `/api/builds/latest` carries the new `name` field, and the watcher polls without errors.
|
||||
Shipped feature: an `autoBuild.times` entry can carry its own `buildCommand` and `name` — a named nightly slot (e.g. `master@nightly`) gets its own branches-view row, retention pool, and permanent latest-green link; restart/retry/recovery repeat a build with its original command and name.
|
||||
|
||||
Update to v0.9.14 (2026-08-28): same procedure, `~/opt/gittally.0.9.13.bak` as the rollback copy; a build was running — interrupted and re-enqueued by the startup recovery as designed (now under its recorded build definition `default`).
|
||||
Verified live: `bin/gittally --version` reports v0.9.14 before the start, the service is `active`, `/` answers 200 with v0.9.14 in the footer, the watcher polls without errors, and the deprecation warning for `branches.master.autoBuild` appears once in the log.
|
||||
Update to v0.9.14 (2026-08-28): same procedure, `~/opt/werkator.0.9.13.bak` as the rollback copy; a build was running — interrupted and re-enqueued by the startup recovery as designed (now under its recorded build definition `default`).
|
||||
Verified live: `bin/werkator --version` reports v0.9.14 before the start, the service is `active`, `/` answers 200 with v0.9.14 in the footer, the watcher polls without errors, and the deprecation warning for `branches.master.autoBuild` appears once in the log.
|
||||
Shipped feature: named build definitions (ADR 0007) — the `builds` section defines jobs with `onPush`/`atTimes` triggers, branch selectors (globs, `activeWithin`), and setting overrides; named builds record under `<branch>@<build>` pools; the v0.9.13 per-slot syntax was removed again.
|
||||
|
||||
Update to v0.9.15 (2026-08-29): same procedure, `~/opt/gittally.0.9.14.bak` as the rollback copy, no build was running.
|
||||
Verified live: `bin/gittally --version` reports v0.9.15 before the start, the service is `active`, the API answers, and the watcher polls without errors.
|
||||
Update to v0.9.15 (2026-08-29): same procedure, `~/opt/werkator.0.9.14.bak` as the rollback copy, no build was running.
|
||||
Verified live: `bin/werkator --version` reports v0.9.15 before the start, the service is `active`, the API answers, and the watcher polls without errors.
|
||||
The leftover `builds.maxConcurrent` in the repository's committed `master` config is ignored with exactly one warning per context instead of failing the configuration — the reason it is tolerated rather than rejected: that config needs a colleague's approval to change, and the installation must not be stuck on a key it is meant to forget.
|
||||
Shipped feature: the `.gittally.yml` committed on a branch takes precedence for its `builds` section as well, and the watcher reads it per origin branch (`git show`, cached by head commit) to decide which of that branch's builds are due.
|
||||
Shipped feature: the `.werkator.yml` committed on a branch takes precedence for its `builds` section as well, and the watcher reads it per origin branch (`git show`, cached by head commit) to decide which of that branch's builds are due.
|
||||
Verified live within seconds of the start: the build definition `reactivate-pi-test-with-full-pitest`, which exists only on the branch `mihoe/reactivate-pi-test` and not in the `master` config, fired its due 05:00 UTC slot, recorded under the pool `mihoe/reactivate-pi-test@reactivate-pi-test-with-full-pitest`, and ran the branch's `pitestFull` command in the build container inherited from the `master` config.
|
||||
|
||||
Update to v0.9.16 (2026-08-29): same procedure, `~/opt/gittally.0.9.15.bak` as the rollback copy.
|
||||
Update to v0.9.16 (2026-08-29): same procedure, `~/opt/werkator.0.9.15.bak` as the rollback copy.
|
||||
A build was running at the first attempt, so the deployment aborted itself before stopping anything; the service was then stopped in the first idle window (waiting rather than interrupting was the operator's call).
|
||||
Verified live: `bin/gittally --version` reports v0.9.16 before the start, the service is `active`, `/releases` lists v0.9.16, and the watcher polls without errors.
|
||||
Verified live: `bin/werkator --version` reports v0.9.16 before the start, the service is `active`, `/releases` lists v0.9.16, and the watcher polls without errors.
|
||||
Shipped features: hourly scheduled builds (`atTimes: ["??:05"]`) and the artifact page showing the command a build actually runs.
|
||||
Verified live: the branch's `atTimes: ["??:00"]` — rejected by v0.9.15 with a warning on every poll cycle — is accepted, and its 06:00 UTC slot fired right after the restart.
|
||||
|
||||
Update to v0.9.17 (2026-08-29): same procedure, `~/opt/gittally.0.9.16.bak` as the rollback copy.
|
||||
Update to v0.9.17 (2026-08-29): same procedure, `~/opt/werkator.0.9.16.bak` as the rollback copy.
|
||||
Deployed under the operator's condition "only if no build is running": the deploy script re-checks `/api/builds/current` immediately before the stop and exits without touching anything when a build is executing.
|
||||
Verified live: `bin/gittally --version` reports v0.9.17 before the start, the service is `active`, `/releases` lists v0.9.17, the served `gittally.js` carries the resume listeners, and no errors in the log.
|
||||
Verified live: `bin/werkator --version` reports v0.9.17 before the start, the service is `active`, `/releases` lists v0.9.17, the served `werkator.js` carries the resume listeners, and no errors in the log.
|
||||
Shipped fix: a page returning from the background fetches the current state immediately instead of showing (and ticking) the state it was left in.
|
||||
|
||||
Update to v0.9.18 (2026-08-29): same procedure, `~/opt/gittally.0.9.17.bak` as the rollback copy, no build was running.
|
||||
Verified live: `bin/gittally --version` reports v0.9.18 before the start, the service is `active`, `/releases` lists v0.9.18, the watcher polls without fetch or poll errors, and the only warnings are the two known `builds.maxConcurrent` lines from the repository's committed config.
|
||||
Shipped feature: a configuration file can declare the GitTally it is written for (`gitTally.version.since`/`below`), so an incompatibility is named instead of silently ignored.
|
||||
Update to v0.9.18 (2026-08-29): same procedure, `~/opt/werkator.0.9.17.bak` as the rollback copy, no build was running.
|
||||
Verified live: `bin/werkator --version` reports v0.9.18 before the start, the service is `active`, `/releases` lists v0.9.18, the watcher polls without fetch or poll errors, and the only warnings are the two known `builds.maxConcurrent` lines from the repository's committed config.
|
||||
Shipped feature: a configuration file can declare the Werkator it is written for (`werkator.version.since`/`below`), so an incompatibility is named instead of silently ignored.
|
||||
The configs of the watched repository declare nothing yet and are unaffected — a missing declaration is never an error.
|
||||
|
||||
Update to v0.9.19 (2026-08-29): same procedure, `~/opt/gittally.0.9.18.bak` as the rollback copy, no build was running.
|
||||
Update to v0.9.19 (2026-08-29): same procedure, `~/opt/werkator.0.9.18.bak` as the rollback copy, no build was running.
|
||||
Shipped feature: a build definition describes its build completely (`requirePullRequest`, the whole `docker` section), `builds.default` is the settings base of every other definition, and the per-branch `branches` section is superseded — read only while nothing defines a build at all.
|
||||
The machine config `.git/gittally/.gittally.yml` was rewritten to the new shape beforehand (backup `.gittally.yml.20260829T085959Z.bak`), in a form valid under both versions: `builds.default` plus `builds.master` for the new one, a reduced `branches` block for v0.9.18, which has no sandbox policy inside a definition.
|
||||
The machine config `.git/werkator/.werkator.yml` was rewritten to the new shape beforehand (backup `.werkator.yml.20260829T085959Z.bak`), in a form valid under both versions: `builds.default` plus `builds.master` for the new one, a reduced `branches` block for v0.9.18, which has no sandbox policy inside a definition.
|
||||
It also drops the machine-local `--no-build-cache` command that had shadowed master's own `buildCommand` for every on-push build; the commands now come from `origin/master`'s committed config.
|
||||
Verified live: `bin/gittally --version` reports v0.9.19 before the start, the service is `active`, `/releases` lists v0.9.19, and the log carries the expected "ignoring the branches section" warning next to the known `builds.maxConcurrent` one.
|
||||
Verified live: `bin/werkator --version` reports v0.9.19 before the start, the service is `active`, `/releases` lists v0.9.19, and the log carries the expected "ignoring the branches section" warning next to the known `builds.maxConcurrent` one.
|
||||
The new `master@master` job fired on the first poll after the restart — its 01:00 slot was due and unmarked for that pool — and runs in `hsadmin-ng-build-env:latest` with `bootJarWithDocumentation`: the pinned `docker.enabled`/`network` reached it through the inheritance from `builds.default`, while its own command won.
|
||||
The legacy `branches` block stays in the machine config for the transition week as the rollback path to v0.9.18; it is inert under v0.9.19.
|
||||
|
||||
Update to v0.9.20 (2026-08-29): same procedure, `~/opt/gittally.0.9.19.bak` as the rollback copy, no build was running.
|
||||
Update to v0.9.20 (2026-08-29): same procedure, `~/opt/werkator.0.9.19.bak` as the rollback copy, no build was running.
|
||||
Shipped feature: a definition's `trigger` block, `!` exclusion patterns in `trigger.branches`, and a per-build Gitea `statusContext`.
|
||||
The machine config had to be migrated in the same window (backup `.gittally.yml.20260829T100842Z.bak`): v0.9.19 drops an unknown `trigger` block silently — which would leave every definition without a trigger — and v0.9.20 refuses the flat keys, so the file is valid for exactly one of the two versions and had to be swapped while the service was down.
|
||||
The machine config had to be migrated in the same window (backup `.werkator.yml.20260829T100842Z.bak`): v0.9.19 drops an unknown `trigger` block silently — which would leave every definition without a trigger — and v0.9.20 refuses the flat keys, so the file is valid for exactly one of the two versions and had to be swapped while the service was down.
|
||||
The new configuration was validated with the new binary (`config:print --full`) after the swap and before the start.
|
||||
Verified live: `--version` reports v0.9.20, the service is `active`, `/releases` lists v0.9.20, the watcher polls without errors, and the two expected warnings (`builds.maxConcurrent`, the ignored `branches` section) are the only ones from the host configuration.
|
||||
The branch-scoped refusal showed itself in production immediately: `mihoe/reactivate-pi-test` still commits its triggers flat, so its committed config is refused with a message naming the branch, the commit, and each definition's offending keys — the watcher falls back to the host's definitions for scheduling, and builds of that branch fail until the file is migrated. Every other branch is unaffected, which is the whole point of the per-file scoping.
|
||||
|
||||
Update to v0.9.21 (2026-08-30): same procedure, `~/opt/gittally.0.9.20.bak` as the rollback copy, no build was running; the machine config needed no change this time.
|
||||
Update to v1.0.0 (2026-08-31), the rename to Werkator, deployed from the branch as the final test of PR#1: `~/opt/gittally.0.9.21.bak` as the rollback copy, no build was running, and an 8.8 KB snapshot of the state directory without its worktrees (`~/gittally-state-20260831T065716Z.tar.gz`) as the way back — everything that cannot be recreated fits in it, the 878 MB are worktrees the migration drops and the next build recreates.
|
||||
The artifact root was moved by hand (`~/.local/state/gittally` to `~/.local/state/werkator`, 1.3 GB, instant on the same filesystem), the state directory moved itself.
|
||||
Two defects surfaced and were fixed before the service was started, both of the silent kind this release is about: the directory move left the machine configuration under its old name in the new directory, a pair of names the lookup did not expect, so the instance resolved empty credentials and none of the host's build definitions; and `init --systemd` wrote a fresh template `.werkator.yml` into the watched working tree beside its committed `.gittally.yml`, which would have made that repository build `./gradlew test` instead of its own command. The bundle was rebuilt from the fixed branch before the units were switched.
|
||||
Verified live: `--version` reports v1.0.0, the service is `active`, the build history is the one from before, the watcher polls without errors, HTTPS through the managed nginx answers 200 with the certificates found under the moved state path, and a master build started by itself — worktree recreated, container `werkator-build-…` running in `hsadmin-ng-build-env:latest` under the new `org.hoennig.werkator` label.
|
||||
The two expected warnings (`builds.maxConcurrent`, the ignored `branches` section) are still the only ones, both from master's committed configuration.
|
||||
|
||||
Update to v0.9.21 (2026-08-30): same procedure, `~/opt/werkator.0.9.20.bak` as the rollback copy, no build was running; the machine config needed no change this time.
|
||||
Shipped feature: an unreachable origin is shown in the web UI (step 19), and a lasting fetch failure is logged once per message instead of once per poll.
|
||||
The occasion was an outage the same morning: the `git.token` in the machine config had been overwritten with a placeholder string, GitTally failed every fetch for 57 minutes, and the branches view kept showing its last known list as if nothing were wrong.
|
||||
Verified live: `--version` reports v0.9.21, the service is `active`, `/` answers 200 with v0.9.21 in the footer, `/api/watcher` reports `lastFetchError: null`, the served `gittally.js` carries `refreshWatcherBanner`, `/branches` carries the banner element, and the only warnings are the two expected ones from the repository's committed config (`builds.maxConcurrent`, the ignored `branches` section).
|
||||
The occasion was an outage the same morning: the `git.token` in the machine config had been overwritten with a placeholder string, Werkator failed every fetch for 57 minutes, and the branches view kept showing its last known list as if nothing were wrong.
|
||||
Verified live: `--version` reports v0.9.21, the service is `active`, `/` answers 200 with v0.9.21 in the footer, `/api/watcher` reports `lastFetchError: null`, the served `werkator.js` carries `refreshWatcherBanner`, `/branches` carries the banner element, and the only warnings are the two expected ones from the repository's committed config (`builds.maxConcurrent`, the ignored `branches` section).
|
||||
|
||||
@@ -6,14 +6,14 @@ Motivated by the vm4006 rollout (step 15, fourth finding): hs.hsadmin.ng's build
|
||||
|
||||
## Problem
|
||||
|
||||
Builds run in git worktrees under `.git/gittally/worktrees/<branchKey>`.
|
||||
Builds run in git worktrees under `.git/werkator/worktrees/<branchKey>`.
|
||||
A worktree's `.git` is a pointer file into the primary repository's `.git/worktrees/<key>`, and `DockerBuildRunner` bind-mounts only the worktree — so every git call inside the build container fails.
|
||||
The legacy script did not have this problem because it built in the primary checkout with the real `.git` present (read-write, including all secrets stored next to it — full exposure).
|
||||
Hard invariant to preserve: a branch build must never be able to reach credentials; `.git/gittally/.gittally.yml` (`git.token`) and the control token live under `.git`.
|
||||
Hard invariant to preserve: a branch build must never be able to reach credentials; `.git/werkator/.werkator.yml` (`git.token`) and the control token live under `.git`.
|
||||
|
||||
## Considered Options
|
||||
|
||||
- **Read-only `.git` mount with `.git/gittally/` masked (chosen)** — three layered mounts, no config key, no workspace mutation; strictly less privileged than legacy.
|
||||
- **Read-only `.git` mount with `.git/werkator/` masked (chosen)** — three layered mounts, no config key, no workspace mutation; strictly less privileged than legacy.
|
||||
- Copy minimal git metadata into the workspace (admin dir plus `objects/info/alternates`) — mutates the workspace, still needs the object database mounted, more moving parts.
|
||||
- Document the limitation and require git-free build commands — pushes the problem onto every watched project; hsadmin-ng shows real builds do call git.
|
||||
|
||||
@@ -22,11 +22,11 @@ Hard invariant to preserve: a branch build must never be able to reach credentia
|
||||
`DockerBuildRunner.gitMetadataMounts(workspace, repoDir)` adds three mounts when (and only when) the workspace is a worktree of `repoDir` (detected via the `gitdir:` pointer file, which must resolve into `repoDir/.git`):
|
||||
|
||||
1. `repoDir/.git` → same path, **read-only**: objects, refs, and the worktree admin metadata become resolvable; object and ref writes stay impossible.
|
||||
2. An empty **tmpfs over `repoDir/.git/gittally`**: masks the machine config (`git.token`), the control token, and all GitTally state; the workspace bind (deeper path, Docker nests mounts by target depth) resurfaces only this build's own worktree inside the masked directory.
|
||||
2. An empty **tmpfs over `repoDir/.git/werkator`**: masks the machine config (`git.token`), the control token, and all Werkator state; the workspace bind (deeper path, Docker nests mounts by target depth) resurfaces only this build's own worktree inside the masked directory.
|
||||
3. `repoDir/.git/worktrees/<key>` → same path, **read-write**: the worktree's admin dir (HEAD, index), so index-refreshing commands like `git status` work.
|
||||
|
||||
No configuration key: the exposure is strictly smaller than the legacy baseline, and a knob would join the pinned sandbox-policy set without a known use case.
|
||||
Remaining, documented exposure: the rest of `.git` — including `.git/config` — is readable by builds; GitTally never stores credentials there (fetch auth uses a secret-free `GIT_ASKPASS` with env-passed credentials).
|
||||
Remaining, documented exposure: the rest of `.git` — including `.git/config` — is readable by builds; Werkator never stores credentials there (fetch auth uses a secret-free `GIT_ASKPASS` with env-passed credentials).
|
||||
|
||||
## Tests
|
||||
|
||||
@@ -35,10 +35,10 @@ Remaining, documented exposure: the rest of `.git` — including `.git/config`
|
||||
## Acceptance Criteria
|
||||
|
||||
- `./gradlew ktlintFormat` then `./gradlew build` is green.
|
||||
- In a real Docker build worktree: `git log`/`git status` succeed inside the container, `.git/gittally/.gittally.yml` and `control-token` are not readable, and a `git push`/ref write fails.
|
||||
- In a real Docker build worktree: `git log`/`git status` succeed inside the container, `.git/werkator/.werkator.yml` and `control-token` are not readable, and a `git push`/ref write fails.
|
||||
- `docs/configuration.md` (docker notes) and the architecture skill describe the mounts.
|
||||
|
||||
## Result (2026-08-10)
|
||||
|
||||
Implemented as designed; verified on vm4006 (see below) and in unit tests.
|
||||
`sh -c 'git log -1 && git status --short && cat .../.git/gittally/.gittally.yml'` inside a build container of the hs.hsadmin.ng worktree: git commands succeed, the machine config read fails with "No such file or directory", `git update-ref` fails on the read-only filesystem.
|
||||
`sh -c 'git log -1 && git status --short && cat .../.git/werkator/.werkator.yml'` inside a build container of the hs.hsadmin.ng worktree: git commands succeed, the machine config read fails with "No such file or directory", `git update-ref` fails on the read-only filesystem.
|
||||
|
||||
@@ -1,14 +1,14 @@
|
||||
# Step 17: Running GitTally on a Managed Webspace (bubblewrap builds + web access)
|
||||
# Step 17: Running Werkator on a Managed Webspace (bubblewrap builds + web access)
|
||||
|
||||
Prerequisites: steps 11, 15, 16.
|
||||
Read `README.md` first.
|
||||
Motivated by running GitTally on Hostsharing **Managed Webspaces**: no root, no Docker daemon, but `bwrap` (bubblewrap) is available and unprivileged user namespaces are allowed.
|
||||
Target use case: GitTally builds GitTally itself on a Managed Webspace; builds needing special dependencies get them from a prepared root filesystem instead of the host.
|
||||
Motivated by running Werkator on Hostsharing **Managed Webspaces**: no root, no Docker daemon, but `bwrap` (bubblewrap) is available and unprivileged user namespaces are allowed.
|
||||
Target use case: Werkator builds Werkator itself on a Managed Webspace; builds needing special dependencies get them from a prepared root filesystem instead of the host.
|
||||
Projects that need Docker for their own tests (hs.hsadmin.ng with Testcontainers) stay on a container host like vm4006 — the webspace is for Docker-free builds only.
|
||||
|
||||
The step covers two halves of the same deployment and is deliberately not split:
|
||||
the build sandbox (most of this document) and the web access under a domain (last section).
|
||||
Without the second half the first one only proves that sandboxed builds work somewhere; without the first one GitTally on a webspace would run builds unsandboxed on the host.
|
||||
Without the second half the first one only proves that sandboxed builds work somewhere; without the first one Werkator on a webspace would run builds unsandboxed on the host.
|
||||
|
||||
## Precondition Check (run on the target webspace first)
|
||||
|
||||
@@ -46,7 +46,7 @@ What 0.8.0 lacks is overlayfs (`--overlay`, added in 0.9.0): a future "throwaway
|
||||
**The runtime bundle runs there — checked, not assumed.** The webspace has glibc 2.36 (Debian 12), below the dev machine's 2.39, which by ADR 0006's original wording would have ruled the bundle out.
|
||||
That wording was wrong and has been corrected: the bundle's highest required symbol version is `GLIBC_2.15`, because `jlink` copies Temurin's prebuilt binaries rather than compiling anything.
|
||||
So no container build and no second build machine are needed for this platform.
|
||||
The bundle's `java.desktop` module does carry X11, ALSA and freetype dependencies, but only in the AWT libraries, which a headless GitTally never loads — as on vm4006.
|
||||
The bundle's `java.desktop` module does carry X11, ALSA and freetype dependencies, but only in the AWT libraries, which a headless Werkator never loads — as on vm4006.
|
||||
|
||||
## Goal
|
||||
|
||||
@@ -58,8 +58,8 @@ No root on the host, no Docker daemon, no changes to the native and Docker runti
|
||||
### Prepared root filesystem
|
||||
|
||||
`debootstrap`/`mmdebstrap` are not available on the webspace, so the rootfs is **not created on the target system**.
|
||||
It is built once elsewhere (any machine with Docker or root, e.g. a container VM) and distributed as an archive, e.g. `gittally-buildenv-trixie-java21.tar.zst`, containing Debian plus all build dependencies (JDK 21, git, locales, project-specific tools).
|
||||
GitTally unpacks it on demand (`tar --no-same-owner`) into `.git/gittally/buildenv/<envKey>/rootfs` — **not** into the working tree.
|
||||
It is built once elsewhere (any machine with Docker or root, e.g. a container VM) and distributed as an archive, e.g. `werkator-buildenv-trixie-java21.tar.zst`, containing Debian plus all build dependencies (JDK 21, git, locales, project-specific tools).
|
||||
Werkator unpacks it on demand (`tar --no-same-owner`) into `.git/werkator/buildenv/<envKey>/rootfs` — **not** into the working tree.
|
||||
Like the Docker image and the Gradle cache volume, the environment is shared across all branch worktrees and survives worktree pruning; `<envKey>` derives from a hash of the configured archive source, so an environment-version change unpacks a fresh rootfs and stale ones can be pruned.
|
||||
|
||||
### Configuration
|
||||
@@ -67,7 +67,7 @@ Like the Docker image and the Gradle cache volume, the environment is shared acr
|
||||
New `branches.<name>.bwrap` section: `enabled`, `rootfs` (path or URL of the archive), `env` (like `docker.env`).
|
||||
`bwrap.enabled` and `bwrap.rootfs` join the **pinned sandbox-policy set** (like `docker.enabled`/`docker.network`): a branch must not be able to switch off its sandbox or substitute a foreign rootfs via its committed config.
|
||||
`docker.enabled` and `bwrap.enabled` are mutually exclusive per branch — reject the config, do not pick silently.
|
||||
Keep the three config places in sync: `GitTallyConfig`, the `InitCommand` templates, `docs/configuration.md`.
|
||||
Keep the three config places in sync: `WerkatorConfig`, the `InitCommand` templates, `docs/configuration.md`.
|
||||
|
||||
### Invocation
|
||||
|
||||
@@ -84,7 +84,7 @@ bwrap --unshare-user --unshare-pid --die-with-parent --uid 0 --gid 0 \
|
||||
/bin/sh -c '<buildCommand>'
|
||||
```
|
||||
|
||||
- The workspace is bound at its **host path**, not at `/workspace`: the worktree's `.git` pointer file contains absolute host paths, and the step-16 git metadata mounts (`--ro-bind` of the primary `.git`, `--tmpfs` over `.git/gittally`, `--bind` of `.git/worktrees/<key>`) port 1:1 — reuse that logic, do not duplicate it.
|
||||
- The workspace is bound at its **host path**, not at `/workspace`: the worktree's `.git` pointer file contains absolute host paths, and the step-16 git metadata mounts (`--ro-bind` of the primary `.git`, `--tmpfs` over `.git/werkator`, `--bind` of `.git/worktrees/<key>`) port 1:1 — reuse that logic, do not duplicate it.
|
||||
- `<buildenv>/home` bound as `/root` gives Gradle a persistent `$HOME` (wrapper dists, `.gradle` caches) — the bwrap sibling of the Docker runner's Gradle cache volume.
|
||||
- `--die-with-parent` plus `--unshare-pid`: cancellation kills the returned `bwrap` process tree and nothing survives — same semantics as the other runtimes.
|
||||
- No ownership repair is needed: files created as uid 0 inside the namespace are owned by the webspace user on the host.
|
||||
@@ -93,7 +93,7 @@ bwrap --unshare-user --unshare-pid --die-with-parent --uid 0 --gid 0 \
|
||||
|
||||
- Network stays shared with the host (Gradle needs it); isolation is weaker than Docker's per-container network.
|
||||
- No Docker inside the sandbox, so no Testcontainers-based tests; build commands must select a Docker-free test subset.
|
||||
For GitTally's own build this means `TestcontainersSmokeTest` must become conditional (`enabledIf` docker present) — that change is part of this step.
|
||||
For Werkator's own build this means `TestcontainersSmokeTest` must become conditional (`enabledIf` docker present) — that change is part of this step.
|
||||
|
||||
## Web Access under a Domain (no Docker, no managed nginx)
|
||||
|
||||
@@ -103,19 +103,19 @@ Three platform-side prerequisites, none of them code:
|
||||
|
||||
1. **Book the "eigener Serverdienst" option** — a service user plus one reserved localhost port, requested from `service@hostsharing.net` stating the service user and the number of ports.
|
||||
Surcharged on Managed Webspaces (RAM contingent in 128 MB steps), included on Managed Servers.
|
||||
The port number is **assigned by Hostsharing** (wiki examples use 34567, 38005/38006), so it goes into `server.port` — GitTally's 18080 is not available by choice.
|
||||
The port number is **assigned by Hostsharing** (wiki examples use 34567, 38005/38006), so it goes into `server.port` — Werkator's 18080 is not available by choice.
|
||||
Sources: [Individuelle Serverdienste](https://www.hostsharing.net/features/individuelle-serverdienste/), [Apache](https://www.hostsharing.net/features/apache/).
|
||||
2. **Run the service as a systemd user unit** — mandatory on Managed Webspaces (no `nohup`, no supervisord); lingering needs a valid login shell configured in HSAdmin, and the account's RAM is capped by a slice (`systemctl status pacs-<account>.slice`).
|
||||
`gittally init --systemd` already generates the unit and the `gittally.env`, whose `JAVA_OPTS=-Xmx…` is what keeps the JVM inside the slice.
|
||||
`werkator init --systemd` already generates the unit and the `werkator.env`, whose `JAVA_OPTS=-Xmx…` is what keeps the JVM inside the slice.
|
||||
Source: [Prozessmanagement mit systemd im Userspace](https://wiki.hostsharing.net/index.php/Prozessmanagement_mit_systemd_im_Userspace).
|
||||
3. **Let's Encrypt** is a domain option ticked in HSAdmin (free, automatic, includes the wildcard subdomain; requires the domain's nameservers to be delegated to Hostsharing), so TLS terminates in the managed Apache.
|
||||
Source: [TLS](https://www.hostsharing.net/doc/managed-operations-platform/tls/).
|
||||
|
||||
### User model: a dedicated unix user, not the package admin
|
||||
|
||||
GitTally runs as its own unix user, e.g. `xyz00-gittally`, with the domain assigned to that same user (`domain.add({set:{name:'…',user:'xyz00-gittally'}})`), so the service, its repository checkout and `~/doms/<domain>/htdocs-ssl/` share one home directory.
|
||||
Werkator runs as its own unix user, e.g. `xyz00-werkator`, with the domain assigned to that same user (`domain.add({set:{name:'…',user:'xyz00-werkator'}})`), so the service, its repository checkout and `~/doms/<domain>/htdocs-ssl/` share one home directory.
|
||||
That is what every Hostsharing service guide does (`xyz00-chat` for Mattermost, `xyz00-tomcat`, `xyz00-cloud` for Nextcloud) and what their user documentation recommends: a domain *can* run under the package admin, but "aus Sicherheitsgründen empfiehlt es sich aber Domains auf separate Domain-Admins aufzuschalten", so a compromise stays inside one home instead of reaching the whole package.
|
||||
Here the argument is stronger than usual, because GitTally checks out foreign commits and executes their build scripts — running that as the package admin would undo the sandbox rationale of this very step.
|
||||
Here the argument is stronger than usual, because Werkator checks out foreign commits and executes their build scripts — running that as the package admin would undo the sandbox rationale of this very step.
|
||||
The service user is named when ordering the daemon port anyway.
|
||||
Sources: [Benutzer](https://www.hostsharing.net/doc/managed-operations-platform/benutzer/), [HSAdmin domain](https://www.hostsharing.net/doc/managed-operations-platform/hsadmin/domain/).
|
||||
|
||||
@@ -137,7 +137,7 @@ RewriteRule .* http://127.0.0.1:<assigned-port>%{REQUEST_URI} [proxy]
|
||||
|
||||
Sources: [Mattermost Installieren](https://wiki.hostsharing.net/index.php/Mattermost_Installieren), [Tomcat Installieren](https://wiki.hostsharing.net/index.php?title=Tomcat_Installieren).
|
||||
|
||||
The matching GitTally configuration:
|
||||
The matching Werkator configuration:
|
||||
|
||||
```yaml
|
||||
server:
|
||||
@@ -148,7 +148,7 @@ server:
|
||||
enabled: false # the managed nginx container is not used on a webspace
|
||||
```
|
||||
|
||||
**This half needs no code change.** GitTally never reconstructs absolute URLs from the request — everything external comes from `server.publicBaseUrl` and the UI links relatively — so the usual reverse-proxy fix `server.forward-headers-strategy` is not needed.
|
||||
**This half needs no code change.** Werkator never reconstructs absolute URLs from the request — everything external comes from `server.publicBaseUrl` and the UI links relatively — so the usual reverse-proxy fix `server.forward-headers-strategy` is not needed.
|
||||
|
||||
Two claims could **not** be verified from a Hostsharing primary source; check them on the target webspace rather than relying on them:
|
||||
|
||||
@@ -169,6 +169,6 @@ Write ADR 0007: bubblewrap user-namespace sandbox as the third build runtime (op
|
||||
|
||||
- The precondition command line above passes on the target webspace; its output is recorded in this file.
|
||||
- `./gradlew ktlintFormat` then `./gradlew build` is green — also on a machine without Docker (Testcontainers smoke test skipped, not failed).
|
||||
- On a Managed Webspace: GitTally (from the runtime bundle) builds a real branch of a repo inside the bwrap sandbox; git commands work in the worktree; `.git/gittally/` is not readable from the build; a write to `/usr` fails.
|
||||
- On a Managed Webspace: Werkator (from the runtime bundle) builds a real branch of a repo inside the bwrap sandbox; git commands work in the worktree; `.git/werkator/` is not readable from the build; a write to `/usr` fails.
|
||||
- On the same webspace: the UI answers over HTTPS under the domain through the Apache `.htaccess` proxy, the service survives a logout and a reboot (systemd lingering), and Gitea statuses carry `publicBaseUrl` links that resolve.
|
||||
- Docs updated: `docs/configuration.md` (bwrap section), architecture skill (third runtime), ADR 0007, and `docs/deployment.md` gains "Hostsharing Managed Webspace" as a third deployment variant — written only once the setup above is verified on a real webspace, not from this plan.
|
||||
|
||||
@@ -11,12 +11,12 @@ The `trigger` block, originally planned here, shipped earlier — see the sectio
|
||||
|
||||
## Precondition Check (run first, do not skip)
|
||||
|
||||
The removal adds a *rejection by name*: a configuration file that still carries a `branches:` key is refused, because a silently ignored section is exactly the failure this step exists to prevent — and the `gitTally.version` check cannot catch it, since it only bites files that declare a version, which none of the hs.hsadmin.ng configs do.
|
||||
The removal adds a *rejection by name*: a configuration file that still carries a `branches:` key is refused, because a silently ignored section is exactly the failure this step exists to prevent — and the `werkator.version` check cannot catch it, since it only bites files that declare a version, which none of the hs.hsadmin.ng configs do.
|
||||
|
||||
So no configuration still in play may contain the section. On vm4006:
|
||||
|
||||
```bash
|
||||
ssh tallyman@vm4006.hostsharing.net 'cd ~/hs.hsadmin.ng && grep -n "^branches:" .git/gittally/.gittally.yml; for b in $(git for-each-ref --format="%(refname:short)" refs/remotes/origin | sed "s|origin/||"); do if git cat-file -e origin/$b:.gittally.yml 2>/dev/null && git show origin/$b:.gittally.yml | grep -qE "^branches:"; then echo "still legacy: $b"; fi; done'
|
||||
ssh tallyman@vm4006.hostsharing.net 'cd ~/hs.hsadmin.ng && grep -n "^branches:" .git/werkator/.werkator.yml; for b in $(git for-each-ref --format="%(refname:short)" refs/remotes/origin | sed "s|origin/||"); do if git cat-file -e origin/$b:.werkator.yml 2>/dev/null && git show origin/$b:.werkator.yml | grep -qE "^branches:"; then echo "still legacy: $b"; fi; done'
|
||||
```
|
||||
|
||||
Expected output: nothing at all.
|
||||
@@ -24,13 +24,13 @@ Expected output: nothing at all.
|
||||
As of 2026-08-29 this listed `master`, five `mihoe/…` branches, and the machine config;
|
||||
the machine config was cleaned up on 2026-08-30, so only the committed ones are left.
|
||||
The plan was: merge `mihoe/reactivate-pi-test` (the first branch with the new shape) to master, rebase the other branches onto the new master, then run this step.
|
||||
Branches without a committed `.gittally.yml` are fine — they build from the machine config.
|
||||
Branches without a committed `.werkator.yml` are fine — they build from the machine config.
|
||||
|
||||
Note that `branches:` also exists as the *selector* key **inside** a build definition (`builds.<name>.branches: ["master"]`). That one stays. Only the top-level section goes. The grep above anchors at the line start for exactly that reason.
|
||||
|
||||
## Code
|
||||
|
||||
- `config/GitTallyConfig.kt`: drop the `branches` property and `AutoBuildConfig`, and `BranchConfig.autoBuild` with it.
|
||||
- `config/WerkatorConfig.kt`: drop the `branches` property and `AutoBuildConfig`, and `BranchConfig.autoBuild` with it.
|
||||
Rename `BranchConfig` to `BuildSettings` — with the section gone it is no longer a schema type but the resolved answer to "what does this build run", which is all it is used for.
|
||||
`buildSettings(branch, build)` then no longer needs the branch lookup: `effectiveBuildDefinitions()[build]?.applyTo(BuildSettings()) ?: BuildSettings()`.
|
||||
Keep the `branch` parameter — the callers pass it and a later per-branch concern would need it back.
|
||||
@@ -39,9 +39,9 @@ Note that `branches:` also exists as the *selector* key **inside** a build defin
|
||||
Reuse `ConfigVersionException` or add a sibling; the message must name the file and say where the settings belong now.
|
||||
- `watcher/Watcher.kt`: delete `enqueueDeprecatedAutoBuilds`, its call in `enqueueDueBranches`, and the `warnedDeprecatedAutoBuild` flag.
|
||||
- `config/ConfigVersion.kt`: set `FORMAT_BROKE_IN` to this release's version and `FORMAT_BROKE_DESCRIPTION` to something like "the per-branch `branches` section was replaced by build definitions".
|
||||
This is the first real use of that mechanism: a file declaring `gitTally.version.since` below this release is then refused with a message naming the change.
|
||||
This is the first real use of that mechanism: a file declaring `werkator.version.since` below this release is then refused with a message naming the change.
|
||||
Note that it only bites files that declare a version — which is why the rejection by name above exists next to it, not instead of it.
|
||||
- `commands/InitCommand.kt`: nothing — the generated template has been `builds`-only with a `trigger` block since v0.9.20. Verify with `gittally init` in a scratch repo.
|
||||
- `commands/InitCommand.kt`: nothing — the generated template has been `builds`-only with a `trigger` block since v0.9.20. Verify with `werkator init` in a scratch repo.
|
||||
|
||||
## Already done: the `trigger` block
|
||||
|
||||
@@ -66,7 +66,6 @@ Add a test that a build whose definition was removed from the config still resol
|
||||
- `docs/configuration.md`: delete the section "The legacy `branches` section"; drop the "only while nothing defines a build" qualifier from the branch-layer section.
|
||||
- `AGENTS.md`: the invariant bullet starting "`builds` or the legacy `branches`, never both" becomes the rejection rule.
|
||||
- `.claude/skills/architecture/SKILL.md`: `resolveBuildSections` no longer chooses between two sections.
|
||||
- `docs/migration-from-legacy.md`: already maps to `builds.<name>`; re-check it reads correctly without the legacy section existing.
|
||||
|
||||
## Production
|
||||
|
||||
@@ -75,13 +74,13 @@ Its legacy `branches` block is deleted, `builds.master` is now `builds.nightly`,
|
||||
The file holds `git`, `server`, `builds.default`, and `builds.nightly`; `config:print --full` resolves both definitions completely, with `nightly` inheriting the docker settings and all three artifact directories.
|
||||
Nothing about the section removal itself is left to do there.
|
||||
The file is 600 by design; a shell redirect creates 644, so check the mode after every edit.
|
||||
Backups: `.gittally.yml.20260829T085959Z.bak` (the pre-v0.9.19 shape) and `.gittally.yml.20260829T100842Z.bak` (the last one carrying the legacy block).
|
||||
Backups: `.werkator.yml.20260829T085959Z.bak` (the pre-v0.9.19 shape) and `.werkator.yml.20260829T100842Z.bak` (the last one carrying the legacy block).
|
||||
|
||||
What remains is deleting the `builds` section from the machine config entirely, as soon as master carries its own.
|
||||
The file then holds `git` and `server` — the secrets and the host's addresses — and nothing that describes a build.
|
||||
|
||||
That works because the pinning strips the *branch* layer only (`ConfigLoader.stripPinned`, applied in `withBranchLayer`).
|
||||
Master's committed `.gittally.yml` is the project layer of the primary checkout and is merged unstripped, so its `docker.enabled: true` and `network: host` are what every branch's builds inherit — including a build a branch invents for itself, because the inheritance from `builds.default` runs after the layers are merged.
|
||||
Master's committed `.werkator.yml` is the project layer of the primary checkout and is merged unstripped, so its `docker.enabled: true` and `network: host` are what every branch's builds inherit — including a build a branch invents for itself, because the inheritance from `builds.default` runs after the layers are merged.
|
||||
The sandbox policy thereby moves from the host to master, where changing it needs a review; it must therefore actually be in master's file before the host's section goes.
|
||||
|
||||
`builds.nightly` goes with it: master's config defines its own `release` job, and the nightly rebuild belongs next to it rather than on the host.
|
||||
@@ -94,12 +93,12 @@ Deploy as usual (`docs/plan/15-runtime-bundle-distribution.md`), only while `/ap
|
||||
|
||||
## Verification
|
||||
|
||||
- `gittally config:print --full` on vm4006 before the restart: no `branches` in the output, every definition complete, and `docker.enabled: true` plus `network: host` on all of them.
|
||||
- `werkator config:print --full` on vm4006 before the restart: no `branches` in the output, every definition complete, and `docker.enabled: true` plus `network: host` on all of them.
|
||||
Once the machine config's `builds` section is gone, that resolves entirely from master's committed file — which is exactly what the check is for.
|
||||
- After the restart: no warnings about a branches section, the watcher polls without errors, and a branch build starts in `hsadmin-ng-build-env:latest`.
|
||||
- Deliberately: point the running instance at a scratch repository whose config still has `branches:` and confirm the error names the file and the way out.
|
||||
|
||||
## Rollback
|
||||
|
||||
Keep the `~/opt/gittally.0.9.20.bak` that this step's deployment creates, plus a timestamped copy of the machine config.
|
||||
Keep the `~/opt/werkator.0.9.20.bak` that this step's deployment creates, plus a timestamped copy of the machine config.
|
||||
Going back below v0.9.19 is not provided for: v0.9.18 reads its sandbox policy from the `branches` block that no configuration carries any more, and would build natively on the host.
|
||||
|
||||
@@ -6,7 +6,7 @@ Read `README.md` first.
|
||||
## Why
|
||||
|
||||
On 2026-08-30 the Gitea token in the machine config on vm4006 was replaced by a placeholder string.
|
||||
For 57 minutes GitTally failed `git fetch --prune origin` every ten seconds and wrote 297 warnings to the journal.
|
||||
For 57 minutes Werkator failed `git fetch --prune origin` every ten seconds and wrote 297 warnings to the journal.
|
||||
The branches view showed a calm, ordinary list the whole time: every branch with its last build, nothing amiss.
|
||||
The failure was noticed only because an expected build did not start, and it took reading the journal to see why.
|
||||
|
||||
@@ -27,11 +27,11 @@ The endpoint needs no change.
|
||||
|
||||
## Code
|
||||
|
||||
- `static/gittally.js`: fetch `/api/watcher` from the same polling cycle that refreshes the view, and show a banner while any of the three conditions holds.
|
||||
- `static/werkator.js`: fetch `/api/watcher` from the same polling cycle that refreshes the view, and show a banner while any of the three conditions holds.
|
||||
Keep the existing discipline — a timeout on the fetch, and a failure of *this* request must never break the view's own refresh.
|
||||
- `templates/fragments.html`: add a `watcher-banner` fragment to the `nav(view)` row so every view inherits it; hidden unless the script fills it.
|
||||
- Wording says what is stale and since when, not just that something failed: the branch list is not updating, since `lastPollAt`, because `<error>`.
|
||||
Timestamps go through the shared formatting — `UiFormats` and `gittally.js` must produce identical formats (invariant in `AGENTS.md`).
|
||||
Timestamps go through the shared formatting — `UiFormats` and `werkator.js` must produce identical formats (invariant in `AGENTS.md`).
|
||||
- Do not overload `live-indicator`: it reports whether the *browser* reaches the server.
|
||||
This banner reports whether the *server* reaches origin. Two independent failures, two independent signals.
|
||||
|
||||
|
||||
+10
-9
@@ -1,6 +1,6 @@
|
||||
# GitTally Rewrite Plan
|
||||
# Werkator Rewrite Plan
|
||||
|
||||
This directory contains the step-by-step plan for rewriting `legacy/gitTally` (bash) as the Kotlin/Spring application in this repository.
|
||||
This directory contains the step-by-step plan for rewriting the legacy bash script 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
|
||||
@@ -9,7 +9,8 @@ Start a fresh Claude Code session and prompt, for example: "Execute docs/plan/01
|
||||
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.
|
||||
2. Read the referenced parts of the legacy bash script only if the step file says so.
|
||||
It was removed from the tree with the rename to Werkator; its last state is `git show 7f55068^:legacy/gitTally`, and `00-legacy-analysis.md` condenses it.
|
||||
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.
|
||||
@@ -22,16 +23,16 @@ The executing session should:
|
||||
- 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`.
|
||||
- Config keys added by a step must be updated in three places: `WerkatorConfig`, 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).
|
||||
- Build results are persisted as a JSON file under `.git/werkator/`, 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.
|
||||
Each branch builds in its own reusable git worktree under `.git/werkator/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).
|
||||
@@ -76,7 +77,7 @@ Added after the 2026-08-10 overhead measurements on vm2176:
|
||||
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
|
||||
- [x] `16-git-in-docker-builds.md` — read-only git metadata inside Docker build containers, with `.git/werkator/` masked
|
||||
|
||||
Added after v0.9.19 replaced the per-branch settings with build definitions (2026-08-29):
|
||||
|
||||
@@ -86,9 +87,9 @@ Added after a silent 57-minute fetch outage on vm4006 (2026-08-30):
|
||||
|
||||
- [x] `19-watcher-health-in-ui.md` — show an unreachable origin in the web UI instead of only in the journal
|
||||
|
||||
Added for running GitTally on Hostsharing Managed Webspaces (2026-08-10):
|
||||
Added for running Werkator 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
|
||||
- [ ] `17-bwrap-build-runtime.md` — Werkator 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.
|
||||
|
||||
@@ -36,8 +36,8 @@ So that stale logs and reports do not stay on disk indefinitely.
|
||||
|
||||
##### Verified by
|
||||
|
||||
- [FileBuildResultRepositoryTest](../../src/test/kotlin/de/hoennig/gittally/build/FileBuildResultRepositoryTest.kt)
|
||||
- [WatcherTest](../../src/test/kotlin/de/hoennig/gittally/watcher/WatcherTest.kt)
|
||||
- [FileBuildResultRepositoryTest](../../src/test/kotlin/de/hoennig/werkator/build/FileBuildResultRepositoryTest.kt)
|
||||
- [WatcherTest](../../src/test/kotlin/de/hoennig/werkator/watcher/WatcherTest.kt)
|
||||
|
||||
#### Scenario#000.02: Count and age combine as independent caps
|
||||
|
||||
@@ -50,7 +50,7 @@ So that one config can bound disk usage by count and staleness by age at the sam
|
||||
|
||||
##### Verified by
|
||||
|
||||
- [FileBuildResultRepositoryTest](../../src/test/kotlin/de/hoennig/gittally/build/FileBuildResultRepositoryTest.kt)
|
||||
- [FileBuildResultRepositoryTest](../../src/test/kotlin/de/hoennig/werkator/build/FileBuildResultRepositoryTest.kt)
|
||||
|
||||
#### Scenario#000.03: A branch's newest build is never age-pruned
|
||||
|
||||
@@ -62,7 +62,7 @@ So that a dormant branch keeps its last build status visible, matching the legac
|
||||
|
||||
##### Verified by
|
||||
|
||||
- [FileBuildResultRepositoryTest](../../src/test/kotlin/de/hoennig/gittally/build/FileBuildResultRepositoryTest.kt)
|
||||
- [FileBuildResultRepositoryTest](../../src/test/kotlin/de/hoennig/werkator/build/FileBuildResultRepositoryTest.kt)
|
||||
|
||||
#### Scenario#000.04: keepLatestGreen shields the latest green build from the age limit
|
||||
|
||||
@@ -75,7 +75,7 @@ So that the permanent `/branches/<branch-key>/…` artifact links stay valid whi
|
||||
|
||||
##### Verified by
|
||||
|
||||
- [FileBuildResultRepositoryTest](../../src/test/kotlin/de/hoennig/gittally/build/FileBuildResultRepositoryTest.kt)
|
||||
- [FileBuildResultRepositoryTest](../../src/test/kotlin/de/hoennig/werkator/build/FileBuildResultRepositoryTest.kt)
|
||||
|
||||
#### Scenario#000.05: The default keeps existing behavior unchanged
|
||||
|
||||
@@ -87,7 +87,7 @@ So that existing installations are unaffected by the new key.
|
||||
|
||||
##### Verified by
|
||||
|
||||
- [FileBuildResultRepositoryTest](../../src/test/kotlin/de/hoennig/gittally/build/FileBuildResultRepositoryTest.kt) (pre-existing count-only prune tests)
|
||||
- [FileBuildResultRepositoryTest](../../src/test/kotlin/de/hoennig/werkator/build/FileBuildResultRepositoryTest.kt) (pre-existing count-only prune tests)
|
||||
|
||||
## The Solution
|
||||
|
||||
|
||||
@@ -39,7 +39,7 @@ So that pull-request branches get their commit status verified as before.
|
||||
|
||||
##### Verified by
|
||||
|
||||
- [WatcherTest: "a branch requiring a pull request is only built when its head matches a pull-request head"](../../src/test/kotlin/de/hoennig/gittally/watcher/WatcherTest.kt)
|
||||
- [WatcherTest: "a branch requiring a pull request is only built when its head matches a pull-request head"](../../src/test/kotlin/de/hoennig/werkator/watcher/WatcherTest.kt)
|
||||
|
||||
#### Scenario#000.02: A gated branch without a pull request is not built!
|
||||
|
||||
@@ -54,7 +54,7 @@ So that work-in-progress branches do not consume build capacity.
|
||||
|
||||
##### Verified by
|
||||
|
||||
- [WatcherTest: "a branch requiring a pull request is only built when its head matches a pull-request head"](../../src/test/kotlin/de/hoennig/gittally/watcher/WatcherTest.kt)
|
||||
- [WatcherTest: "a branch requiring a pull request is only built when its head matches a pull-request head"](../../src/test/kotlin/de/hoennig/werkator/watcher/WatcherTest.kt)
|
||||
|
||||
#### Scenario#000.03: Pull-request detection works without an API token!
|
||||
|
||||
@@ -66,7 +66,7 @@ So that GitTally needs no Gitea credentials for this feature.
|
||||
|
||||
##### Verified by
|
||||
|
||||
- [GitServiceTest: "pullRequestHeads returns the head commits of the remote's pull-request refs"](../../src/test/kotlin/de/hoennig/gittally/git/GitServiceTest.kt)
|
||||
- [GitServiceTest: "pullRequestHeads returns the head commits of the remote's pull-request refs"](../../src/test/kotlin/de/hoennig/werkator/git/GitServiceTest.kt)
|
||||
|
||||
#### Scenario#000.04: Ungated setups make no extra remote calls!
|
||||
|
||||
@@ -78,7 +78,7 @@ So that existing installations see no new network traffic.
|
||||
|
||||
##### Verified by
|
||||
|
||||
- [WatcherTest: "pull-request refs are not queried when no due branch requires a pull request"](../../src/test/kotlin/de/hoennig/gittally/watcher/WatcherTest.kt)
|
||||
- [WatcherTest: "pull-request refs are not queried when no due branch requires a pull request"](../../src/test/kotlin/de/hoennig/werkator/watcher/WatcherTest.kt)
|
||||
|
||||
#### Scenario#000.05: A branch entry overrides the default!
|
||||
|
||||
@@ -91,7 +91,7 @@ So that permanent branches like `main` keep building after merges, whose merge c
|
||||
|
||||
##### Verified by
|
||||
|
||||
- [WatcherTest: "a branch entry overrides requirePullRequest from the default entry"](../../src/test/kotlin/de/hoennig/gittally/watcher/WatcherTest.kt)
|
||||
- [WatcherTest: "a branch entry overrides requirePullRequest from the default entry"](../../src/test/kotlin/de/hoennig/werkator/watcher/WatcherTest.kt)
|
||||
|
||||
#### Scenario#000.06: Auto builds respect the gate!
|
||||
|
||||
@@ -105,7 +105,7 @@ So that scheduled rebuilds follow the same policy as push-triggered builds.
|
||||
|
||||
##### Verified by
|
||||
|
||||
- [WatcherTest: "an auto build requiring a pull request is skipped and its slot stays untriggered"](../../src/test/kotlin/de/hoennig/gittally/watcher/WatcherTest.kt)
|
||||
- [WatcherTest: "an auto build requiring a pull request is skipped and its slot stays untriggered"](../../src/test/kotlin/de/hoennig/werkator/watcher/WatcherTest.kt)
|
||||
|
||||
#### Scenario#000.07: The gate can be disabled globally for plain git origins!
|
||||
|
||||
@@ -119,7 +119,7 @@ So that the same committed configuration works on environments whose origin is p
|
||||
|
||||
##### Verified by
|
||||
|
||||
- [WatcherTest: "a disabled pull-request gate builds gated branches on plain-git origins without querying pull-request refs"](../../src/test/kotlin/de/hoennig/gittally/watcher/WatcherTest.kt)
|
||||
- [WatcherTest: "a disabled pull-request gate builds gated branches on plain-git origins without querying pull-request refs"](../../src/test/kotlin/de/hoennig/werkator/watcher/WatcherTest.kt)
|
||||
|
||||
## The Solution
|
||||
|
||||
|
||||
@@ -34,8 +34,8 @@ So that links in READMEs, wikis, and bookmarks stay valid across new builds.
|
||||
|
||||
##### Verified by
|
||||
|
||||
- [ArtifactFileControllerTest](../../src/test/kotlin/de/hoennig/gittally/server/ArtifactFileControllerTest.kt)
|
||||
- [BranchPermalinksTest](../../src/test/kotlin/de/hoennig/gittally/server/BranchPermalinksTest.kt)
|
||||
- [ArtifactFileControllerTest](../../src/test/kotlin/de/hoennig/werkator/server/ArtifactFileControllerTest.kt)
|
||||
- [BranchPermalinksTest](../../src/test/kotlin/de/hoennig/werkator/server/BranchPermalinksTest.kt)
|
||||
|
||||
#### Scenario#000.02: Directory URLs serve their index page like a static web server
|
||||
|
||||
@@ -49,7 +49,7 @@ So that legacy-style report links such as `/branches/main/reports/build/doc/` wo
|
||||
|
||||
##### Verified by
|
||||
|
||||
- [ArtifactFileControllerTest](../../src/test/kotlin/de/hoennig/gittally/server/ArtifactFileControllerTest.kt)
|
||||
- [ArtifactFileControllerTest](../../src/test/kotlin/de/hoennig/werkator/server/ArtifactFileControllerTest.kt)
|
||||
|
||||
#### Scenario#000.03: The bare permanent URL renders a permanent artifact index
|
||||
|
||||
@@ -63,8 +63,8 @@ So that users can browse the latest green artifacts from one stable bookmark.
|
||||
|
||||
##### Verified by
|
||||
|
||||
- [UiControllerTest](../../src/test/kotlin/de/hoennig/gittally/server/UiControllerTest.kt)
|
||||
- [PermanentBranchRoutesTest](../../src/test/kotlin/de/hoennig/gittally/server/PermanentBranchRoutesTest.kt) (the `/branches`, `/branches/<key>`, and `/branches/<key>/<path>` routes coexist)
|
||||
- [UiControllerTest](../../src/test/kotlin/de/hoennig/werkator/server/UiControllerTest.kt)
|
||||
- [PermanentBranchRoutesTest](../../src/test/kotlin/de/hoennig/werkator/server/PermanentBranchRoutesTest.kt) (the `/branches`, `/branches/<key>`, and `/branches/<key>/<path>` routes coexist)
|
||||
|
||||
#### Scenario#000.04: Green-only and unambiguous resolution
|
||||
|
||||
@@ -80,7 +80,7 @@ So that a permanent link never points at broken artifacts or the wrong branch.
|
||||
|
||||
##### Verified by
|
||||
|
||||
- [BranchPermalinksTest](../../src/test/kotlin/de/hoennig/gittally/server/BranchPermalinksTest.kt)
|
||||
- [BranchPermalinksTest](../../src/test/kotlin/de/hoennig/werkator/server/BranchPermalinksTest.kt)
|
||||
|
||||
#### Scenario#000.05: The latest green build survives pruning
|
||||
|
||||
@@ -94,8 +94,8 @@ So that a permanent link stays valid while newer builds fail, as long as the bra
|
||||
|
||||
##### Verified by
|
||||
|
||||
- [FileBuildResultRepositoryTest](../../src/test/kotlin/de/hoennig/gittally/build/FileBuildResultRepositoryTest.kt)
|
||||
- [WatcherTest](../../src/test/kotlin/de/hoennig/gittally/watcher/WatcherTest.kt)
|
||||
- [FileBuildResultRepositoryTest](../../src/test/kotlin/de/hoennig/werkator/build/FileBuildResultRepositoryTest.kt)
|
||||
- [WatcherTest](../../src/test/kotlin/de/hoennig/werkator/watcher/WatcherTest.kt)
|
||||
|
||||
#### Scenario#000.06: The branches view links the permanent URL
|
||||
|
||||
@@ -108,8 +108,8 @@ So that users can discover the permanent link without constructing it by hand.
|
||||
|
||||
##### Verified by
|
||||
|
||||
- [BranchListingTest](../../src/test/kotlin/de/hoennig/gittally/server/BranchListingTest.kt)
|
||||
- [UiControllerTest](../../src/test/kotlin/de/hoennig/gittally/server/UiControllerTest.kt)
|
||||
- [BranchListingTest](../../src/test/kotlin/de/hoennig/werkator/server/BranchListingTest.kt)
|
||||
- [UiControllerTest](../../src/test/kotlin/de/hoennig/werkator/server/UiControllerTest.kt)
|
||||
|
||||
## The Solution
|
||||
|
||||
|
||||
@@ -42,8 +42,8 @@ Each item is a TODO with the background that justifies it.
|
||||
|
||||
#### TODO 1 — Restrict the Gitea-token config file to the owner at creation
|
||||
|
||||
- [x] In [`InitCommand.kt:86-106`](../../src/main/kotlin/de/hoennig/gittally/commands/InitCommand.kt), create `.git/gittally/.gittally.yml` and its parent `.git/gittally/` with `0600`/`0700`, atomically at creation (as [`GitAskPass`](../../src/main/kotlin/de/hoennig/gittally/git/GitAskPass.kt) does), not via plain `writeText` at the umask default.
|
||||
**Done:** both `init` paths now go through [`SecretFiles`](../../src/main/kotlin/de/hoennig/gittally/SecretFiles.kt), which sets the mode as a file attribute at creation.
|
||||
- [x] In [`InitCommand.kt:86-106`](../../src/main/kotlin/de/hoennig/werkator/commands/InitCommand.kt), create `.git/gittally/.gittally.yml` and its parent `.git/gittally/` with `0600`/`0700`, atomically at creation (as [`GitAskPass`](../../src/main/kotlin/de/hoennig/werkator/git/GitAskPass.kt) does), not via plain `writeText` at the umask default.
|
||||
**Done:** both `init` paths now go through [`SecretFiles`](../../src/main/kotlin/de/hoennig/werkator/SecretFiles.kt), which sets the mode as a file attribute at creation.
|
||||
|
||||
**Background.**
|
||||
`init` creates the file it labels "secrets" — where the operator pastes the Gitea API token — with `writeText` and no permission restriction, so it inherits the umask (typically `0644`, world-readable).
|
||||
@@ -52,7 +52,7 @@ On a shared host (Hostsharing is a multi-tenant deployment target, per ADR 0005)
|
||||
|
||||
#### TODO 2 — Stop handing the control token to every unauthenticated reader
|
||||
|
||||
- [x] Reconsider the token distribution in [`UiController.kt:186`](../../src/main/kotlin/de/hoennig/gittally/server/UiController.kt) and [`fragments.html:9`](../../src/main/resources/templates/fragments.html): do not embed the live token in public HTML, or gate the pages behind the same check as the mutations.
|
||||
- [x] Reconsider the token distribution in [`UiController.kt:186`](../../src/main/kotlin/de/hoennig/werkator/server/UiController.kt) and [`fragments.html:9`](../../src/main/resources/templates/fragments.html): do not embed the live token in public HTML, or gate the pages behind the same check as the mutations.
|
||||
**Done in v0.9.10, without gating the pages.** Public read access is a requirement, not an oversight: build states, logs and artifacts must stay linkable without a login.
|
||||
So the `<meta>` tag is gone and `gittally.js` keeps the token in `localStorage`, asking for it once per browser (the operator reads it from `.git/gittally/control-token`, which needs shell access to the host).
|
||||
The token is a real secret again, and as a request header it stays inherently CSRF-safe — a foreign origin cannot set it without a CORS grant.
|
||||
@@ -61,7 +61,7 @@ On a shared host (Hostsharing is a multi-tenant deployment target, per ADR 0005)
|
||||
Superseded: read access no longer implies write access. `docs/deployment.md` gained a "Control Token" section describing the split.
|
||||
|
||||
**Background.**
|
||||
Every server-rendered page embeds the live control token in `<meta name="gittally-control-token">` so [`gittally.js`](../../src/main/resources/static/gittally.js) can read it, but no GET is authenticated.
|
||||
Every server-rendered page embeds the live control token in `<meta name="gittally-control-token">` so [`gittally.js`](../../src/main/resources/static/werkator.js) can read it, but no GET is authenticated.
|
||||
So `curl -s http://host:18080/ | grep gittally-control-token` yields the token, which unlocks restart/cancel/delete.
|
||||
Read access therefore equals write access, and the token provides no real second trust tier.
|
||||
Blast radius is limited to build-lifecycle operations (a DoS/integrity concern, not secret disclosure or RCE), which is why this is a design flaw rather than Critical — but the token gives a false sense of protection.
|
||||
@@ -70,7 +70,7 @@ Blast radius is limited to build-lifecycle operations (a DoS/integrity concern,
|
||||
|
||||
#### TODO 3 — Accept the control token via header only
|
||||
|
||||
- [x] Remove the `token` query-parameter variant from the three mutating endpoints in [`BuildsApiController.kt:90,115,129`](../../src/main/kotlin/de/hoennig/gittally/server/BuildsApiController.kt); keep only the `X-GitTally-Token` header (which the bundled UI already uses).
|
||||
- [x] Remove the `token` query-parameter variant from the three mutating endpoints in [`BuildsApiController.kt:90,115,129`](../../src/main/kotlin/de/hoennig/werkator/server/BuildsApiController.kt); keep only the `X-GitTally-Token` header (which the bundled UI already uses).
|
||||
|
||||
**Background.**
|
||||
Tokens in URLs are routinely written to access logs, reverse-proxy logs, browser history, and the `Referer` header on outbound navigation.
|
||||
@@ -79,7 +79,7 @@ The query-param path exists only for legacy convenience.
|
||||
|
||||
#### TODO 4 — Redact the Gitea token in `config:print`
|
||||
|
||||
- [x] Mask `git.token` (and any future secret) by default in [`ConfigPrintCommand.kt:20-31`](../../src/main/kotlin/de/hoennig/gittally/commands/ConfigPrintCommand.kt); gate the plaintext value behind an explicit `--show-secrets` flag.
|
||||
- [x] Mask `git.token` (and any future secret) by default in [`ConfigPrintCommand.kt:20-31`](../../src/main/kotlin/de/hoennig/werkator/commands/ConfigPrintCommand.kt); gate the plaintext value behind an explicit `--show-secrets` flag.
|
||||
Masked as `***` on both the `--full` and the raw path, with a leading YAML comment naming the flag, so the output stays parseable when piped.
|
||||
- [x] Update `tools/setup-gittally-instance:272`, which currently steers the operator to run `config:print --full` to view the token.
|
||||
|
||||
@@ -89,7 +89,7 @@ There is no redaction and no masked default.
|
||||
|
||||
#### TODO 5 — Reduce information disclosure on the unauthenticated read API
|
||||
|
||||
- [x] Decide whether build-log streaming ([`BuildsApiController`](../../src/main/kotlin/de/hoennig/gittally/server/BuildsApiController.kt) `/api/builds/current/{key}/log`), [`SystemApiController`](../../src/main/kotlin/de/hoennig/gittally/server/SystemApiController.kt), and [`WatcherApiController`](../../src/main/kotlin/de/hoennig/gittally/server/WatcherApiController.kt) should stay fully public, or be gated / scrubbed.
|
||||
- [x] Decide whether build-log streaming ([`BuildsApiController`](../../src/main/kotlin/de/hoennig/werkator/server/BuildsApiController.kt) `/api/builds/current/{key}/log`), [`SystemApiController`](../../src/main/kotlin/de/hoennig/werkator/server/SystemApiController.kt), and [`WatcherApiController`](../../src/main/kotlin/de/hoennig/werkator/server/WatcherApiController.kt) should stay fully public, or be gated / scrubbed.
|
||||
**Decided: they stay fully public, no scrubbing.** The watched projects (GitTally itself and hs.hsadmin.ng) are open source, the repositories hold no secrets, and the builds run tests against test data — credentials appearing in a log are fixtures, not real ones. Builds neither deploy nor sign; the only planned artifact is a jar.
|
||||
Public logs are also the point of the tool: a red build must be diagnosable from the link in the Gitea status without a login.
|
||||
This is a property of the watched project, not of GitTally: an installation whose builds touch real credentials must keep its instance off the public internet (reverse proxy or `bindAddress: 127.0.0.1`), because GitTally offers no per-endpoint gating.
|
||||
@@ -104,14 +104,14 @@ Raw build output may contain secrets echoed by build scripts; `/api/system` expo
|
||||
|
||||
A branch is built with its own build settings: `.gittally.yml` from the **build worktree** (the commit being built) overrides the `.git`/primary config — except for a pinned set that a branch must never control. **Implemented in this PR.**
|
||||
|
||||
- [x] Worktree config layer for builds via [`ConfigLoader.loadForWorktree`](../../src/main/kotlin/de/hoennig/gittally/config/ConfigLoader.kt), wired into the two build-time config consumers ([`BuildExecutor.branchConfig`](../../src/main/kotlin/de/hoennig/gittally/build/BuildExecutor.kt), [`FileArtifactStore.branchConfig`](../../src/main/kotlin/de/hoennig/gittally/artifacts/FileArtifactStore.kt)) — both already hold the prepared worktree path. Precedence is worktree > `.git` > project.
|
||||
- [x] Worktree config layer for builds via [`ConfigLoader.loadForWorktree`](../../src/main/kotlin/de/hoennig/werkator/config/ConfigLoader.kt), wired into the two build-time config consumers ([`BuildExecutor.branchConfig`](../../src/main/kotlin/de/hoennig/werkator/build/BuildExecutor.kt), [`FileArtifactStore.branchConfig`](../../src/main/kotlin/de/hoennig/werkator/artifacts/FileArtifactStore.kt)) — both already hold the prepared worktree path. Precedence is worktree > `.git` > project.
|
||||
- [x] **Pinned to `.git`/primary — stripped from the worktree layer:** `git`, `gitea`, `server` (secrets + server-side), and the sandbox policy `docker.enabled`/`docker.network`. A branch cannot disable its container or change its network mode.
|
||||
- [x] Worktree-overridable: `buildCommand`, `cleanCommand`, `artifactDirs`, `stdoutLog`/`stderrLog`, `autoBuild`, and `docker.image`/`dockerfile`/`context`/`env`.
|
||||
- [x] Pinned set enforced in code (`ConfigLoader.stripPinned`), documented in `docs/configuration.md`, and asserted as an invariant in `AGENTS.md`.
|
||||
- [ ] **Deferred:** `autoBuild` scheduling and `requirePullRequest` are still read from the primary config, not the worktree — the watcher evaluates them *before* a build (and thus a worktree) exists. Sourcing them per-branch would need the watcher to read the branch's committed config directly (e.g. via `git show <branch>:.gittally.yml`); out of scope here.
|
||||
|
||||
**Background.**
|
||||
The build command is executed via `bash -c "$3"` inside the build container ([`DockerBuildRunner.kt:285`](../../src/main/kotlin/de/hoennig/gittally/build/DockerBuildRunner.kt)).
|
||||
The build command is executed via `bash -c "$3"` inside the build container ([`DockerBuildRunner.kt:285`](../../src/main/kotlin/de/hoennig/werkator/build/DockerBuildRunner.kt)).
|
||||
Letting a branch define its own `buildCommand` is not a new risk — a CI already runs arbitrary code from that commit; the container is the sandbox.
|
||||
The real escalation is a branch turning the sandbox **off**: if the worktree could set `docker.enabled: false` (or host `docker.network`), the build would run natively on the host — which is why those two keys are pinned.
|
||||
Secrets are also safe from the build process (the Gitea token is used only by the server/watcher and is never placed in the build environment — `runCommand` passes only `mapOf("branch" to ...)`), and the whole `git`/`gitea`/`server` sections are stripped from the worktree layer as defense in depth.
|
||||
@@ -121,7 +121,7 @@ Before this PR all build config was loaded from the primary checkout via `config
|
||||
|
||||
#### TODO 7 — Default `bindAddress` to `127.0.0.1`
|
||||
|
||||
- [x] Change the default in [`GitTallyConfig.kt:21`](../../src/main/kotlin/de/hoennig/gittally/config/GitTallyConfig.kt) and the `init` template ([`InitCommand.kt:126`](../../src/main/kotlin/de/hoennig/gittally/commands/InitCommand.kt)) from `0.0.0.0` to `127.0.0.1`; require operators to opt into all-interfaces.
|
||||
- [x] Change the default in [`GitTallyConfig.kt:21`](../../src/main/kotlin/de/hoennig/werkator/config/WerkatorConfig.kt) and the `init` template ([`InitCommand.kt:126`](../../src/main/kotlin/de/hoennig/werkator/commands/InitCommand.kt)) from `0.0.0.0` to `127.0.0.1`; require operators to opt into all-interfaces.
|
||||
Shipped as v0.9.9 with the migration note in the release notes, `docs/configuration.md` ("Notes on `server.bindAddress`") and `docs/deployment.md`: existing configs keep their explicit value, and the managed nginx now needs `0.0.0.0` set deliberately.
|
||||
|
||||
**Background.**
|
||||
@@ -130,7 +130,7 @@ The deployment doc already recommends `127.0.0.1`; the default and template shou
|
||||
|
||||
#### TODO 8 — Compare fixed-length hashes in the token check
|
||||
|
||||
- [x] In [`ControlTokenService.kt:35-37`](../../src/main/kotlin/de/hoennig/gittally/server/ControlTokenService.kt), compare `SHA-256(submitted)` against `SHA-256(secret)` with `MessageDigest.isEqual`, so the comparison is always over equal-length buffers.
|
||||
- [x] In [`ControlTokenService.kt:35-37`](../../src/main/kotlin/de/hoennig/werkator/server/ControlTokenService.kt), compare `SHA-256(submitted)` against `SHA-256(secret)` with `MessageDigest.isEqual`, so the comparison is always over equal-length buffers.
|
||||
|
||||
**Background.**
|
||||
`MessageDigest.isEqual` returns early on a length mismatch, leaking the token length via timing.
|
||||
@@ -138,7 +138,7 @@ Largely theoretical given the 192-bit CSPRNG token, but a cheap deviation from c
|
||||
|
||||
#### TODO 9 — Add `--` before positional refnames in git calls
|
||||
|
||||
- [x] Insert `--` before the branch argument in `checkout`, `fetchBranch`, and `resetHardToOrigin` in [`GitService.kt:145,40,155`](../../src/main/kotlin/de/hoennig/gittally/git/GitService.kt) (e.g. `git switch -- <branch>`).
|
||||
- [x] Insert `--` before the branch argument in `checkout`, `fetchBranch`, and `resetHardToOrigin` in [`GitService.kt:145,40,155`](../../src/main/kotlin/de/hoennig/werkator/git/GitService.kt) (e.g. `git switch -- <branch>`).
|
||||
**Done for `checkout` and `fetchBranch`.** `resetHardToOrigin` keeps its plain form: `git reset --hard -- <commit>` is rejected (`fatal: Cannot do hard reset with paths`), and its argument is already prefixed with `origin/`, so it can never start with `-`.
|
||||
|
||||
**Background.**
|
||||
@@ -147,8 +147,8 @@ These three methods currently have no production callers and the actively-used p
|
||||
|
||||
#### TODO 10 — Create secret files restricted atomically
|
||||
|
||||
- [x] Set the mode at creation for the control-token file ([`ControlTokenService.kt:29-30`](../../src/main/kotlin/de/hoennig/gittally/server/ControlTokenService.kt)) and the setup-script YAML (`tools/setup-gittally-instance:253`), instead of `chmod 0600` after the write.
|
||||
**Done:** the control-token file via [`SecretFiles`](../../src/main/kotlin/de/hoennig/gittally/SecretFiles.kt), the setup script by writing the YAML in a `umask 077` subshell instead of `chmod`-ing afterwards.
|
||||
- [x] Set the mode at creation for the control-token file ([`ControlTokenService.kt:29-30`](../../src/main/kotlin/de/hoennig/werkator/server/ControlTokenService.kt)) and the setup-script YAML (`tools/setup-gittally-instance:253`), instead of `chmod 0600` after the write.
|
||||
**Done:** the control-token file via [`SecretFiles`](../../src/main/kotlin/de/hoennig/werkator/SecretFiles.kt), the setup script by writing the YAML in a `umask 077` subshell instead of `chmod`-ing afterwards.
|
||||
|
||||
**Background.**
|
||||
Both currently write the file at the umask default and tighten it afterward, leaving a brief window where the secret exists world-readable.
|
||||
@@ -175,11 +175,11 @@ A small TOCTOU gap; `GitAskPass`'s atomic-at-creation approach is the pattern to
|
||||
|
||||
Recorded so future changes do not silently regress these.
|
||||
|
||||
- **Path traversal in artifact serving** — [`ArtifactFileController`](../../src/main/kotlin/de/hoennig/gittally/server/ArtifactFileController.kt) normalizes then enforces `startsWith(artifactDir)` and `isRegularFile(..., NOFOLLOW_LINKS)` (rejects symlink escape); [`FileArtifactStore`](../../src/main/kotlin/de/hoennig/gittally/artifacts/FileArtifactStore.kt) whitelists the key to `[A-Za-z0-9._-]+` and requires `dir.parent == branchesDir`.
|
||||
- **Command injection** — every git/docker/certbot/nginx call uses `ProcessBuilder(List<String>)` ([`GitCommandRunner.kt`](../../src/main/kotlin/de/hoennig/gittally/git/GitCommandRunner.kt)); no `Runtime.exec(String)`, no shell-string interpolation; the only `sh -c`/`bash -c` uses pass data as positional args.
|
||||
- **Branch-name → filesystem** — always routed through [`ArtifactKeys.sanitize`](../../src/main/kotlin/de/hoennig/gittally/build/ArtifactKeys.kt) (`/` → `_`) plus a SHA suffix, so worktree/container/volume names cannot traverse.
|
||||
- **Path traversal in artifact serving** — [`ArtifactFileController`](../../src/main/kotlin/de/hoennig/werkator/server/ArtifactFileController.kt) normalizes then enforces `startsWith(artifactDir)` and `isRegularFile(..., NOFOLLOW_LINKS)` (rejects symlink escape); [`FileArtifactStore`](../../src/main/kotlin/de/hoennig/werkator/artifacts/FileArtifactStore.kt) whitelists the key to `[A-Za-z0-9._-]+` and requires `dir.parent == branchesDir`.
|
||||
- **Command injection** — every git/docker/certbot/nginx call uses `ProcessBuilder(List<String>)` ([`GitCommandRunner.kt`](../../src/main/kotlin/de/hoennig/werkator/git/GitCommandRunner.kt)); no `Runtime.exec(String)`, no shell-string interpolation; the only `sh -c`/`bash -c` uses pass data as positional args.
|
||||
- **Branch-name → filesystem** — always routed through [`ArtifactKeys.sanitize`](../../src/main/kotlin/de/hoennig/werkator/build/ArtifactKeys.kt) (`/` → `_`) plus a SHA suffix, so worktree/container/volume names cannot traverse.
|
||||
- **XSS** — no `th:utext` in any template; `gittally.js` builds all DOM via `createElement` + `textContent`/`dataset`, no `innerHTML`.
|
||||
- **SSRF** — the Gitea status proxy validates the commit against `[0-9a-fA-F]{7,40}` ([`StatusApiController.kt`](../../src/main/kotlin/de/hoennig/gittally/server/StatusApiController.kt)); the Gitea base URL/owner/repo/token come from config, not the request.
|
||||
- **SSRF** — the Gitea status proxy validates the commit against `[0-9a-fA-F]{7,40}` ([`StatusApiController.kt`](../../src/main/kotlin/de/hoennig/werkator/server/StatusApiController.kt)); the Gitea base URL/owner/repo/token come from config, not the request.
|
||||
- **Deserialization** — Jackson JSON/YAML without polymorphic/default typing (no gadget-chain RCE); unreadable state files degrade to empty.
|
||||
- **Credential transport** — Gitea token sent as an `Authorization` header, never in a URL ([`GiteaClient.kt`](../../src/main/kotlin/de/hoennig/gittally/gitea/GiteaClient.kt)); git auth via env-based `GIT_ASKPASS` with a `0700` script containing no secrets, deleted in `finally`; TLS verification never disabled.
|
||||
- **nginx/certbot** — `serverName`/`upstreamHost` validated against `[A-Za-z0-9][A-Za-z0-9.-]*` before substitution ([`NginxProxyManager.kt`](../../src/main/kotlin/de/hoennig/gittally/server/NginxProxyManager.kt)); ports range-checked.
|
||||
- **Credential transport** — Gitea token sent as an `Authorization` header, never in a URL ([`GiteaClient.kt`](../../src/main/kotlin/de/hoennig/werkator/gitea/GiteaClient.kt)); git auth via env-based `GIT_ASKPASS` with a `0700` script containing no secrets, deleted in `finally`; TLS verification never disabled.
|
||||
- **nginx/certbot** — `serverName`/`upstreamHost` validated against `[A-Za-z0-9][A-Za-z0-9.-]*` before substitution ([`NginxProxyManager.kt`](../../src/main/kotlin/de/hoennig/werkator/server/NginxProxyManager.kt)); ports range-checked.
|
||||
|
||||
@@ -35,8 +35,8 @@ So that critical load is visible at a glance.
|
||||
|
||||
##### Verified by
|
||||
|
||||
- [UiViewsTest — "utilization highlights warn from 80% and crit from 90% of the total"](../../src/test/kotlin/de/hoennig/gittally/server/UiViewsTest.kt)
|
||||
- [UiViewsTest — "only the used rows with a total get the critical highlighting"](../../src/test/kotlin/de/hoennig/gittally/server/UiViewsTest.kt)
|
||||
- [UiViewsTest — "utilization highlights warn from 80% and crit from 90% of the total"](../../src/test/kotlin/de/hoennig/werkator/server/UiViewsTest.kt)
|
||||
- [UiViewsTest — "only the used rows with a total get the critical highlighting"](../../src/test/kotlin/de/hoennig/werkator/server/UiViewsTest.kt)
|
||||
|
||||
#### Scenario#000.02: Unavailable metrics are never highlighted
|
||||
|
||||
@@ -48,7 +48,7 @@ So that hosts without `/proc` (no metrics, `n/a` cells) render unchanged.
|
||||
|
||||
##### Verified by
|
||||
|
||||
- [UiViewsTest — "utilization highlighting is off when a value or the total is unavailable"](../../src/test/kotlin/de/hoennig/gittally/server/UiViewsTest.kt)
|
||||
- [UiViewsTest — "utilization highlighting is off when a value or the total is unavailable"](../../src/test/kotlin/de/hoennig/werkator/server/UiViewsTest.kt)
|
||||
|
||||
## The Solution
|
||||
|
||||
|
||||
@@ -37,7 +37,7 @@ So that a service restart never loses a build or marks its commit as failed.
|
||||
|
||||
##### Verified by
|
||||
|
||||
- [BuildExecutorTest — "shutdown kills an executing build and records INTERRUPTED, not FAILED"](../../src/test/kotlin/de/hoennig/gittally/build/BuildExecutorTest.kt)
|
||||
- [BuildExecutorTest — "shutdown kills an executing build and records INTERRUPTED, not FAILED"](../../src/test/kotlin/de/hoennig/werkator/build/BuildExecutorTest.kt)
|
||||
|
||||
#### Scenario#000.02: A queued build stays PENDING over a shutdown
|
||||
|
||||
@@ -50,7 +50,7 @@ So that queued builds survive a restart the same way executing builds do.
|
||||
|
||||
##### Verified by
|
||||
|
||||
- [BuildExecutorTest — "a build still queued at shutdown stays PENDING for the startup recovery"](../../src/test/kotlin/de/hoennig/gittally/build/BuildExecutorTest.kt)
|
||||
- [BuildExecutorTest — "a build still queued at shutdown stays PENDING for the startup recovery"](../../src/test/kotlin/de/hoennig/werkator/build/BuildExecutorTest.kt)
|
||||
|
||||
#### Scenario#000.03: No failure status is posted to Gitea for an interrupted build
|
||||
|
||||
@@ -63,8 +63,8 @@ So that a commit does not turn red because of a service restart.
|
||||
|
||||
##### Verified by
|
||||
|
||||
- [GiteaStateMappingTest](../../src/test/kotlin/de/hoennig/gittally/gitea/GiteaStateMappingTest.kt)
|
||||
- [GiteaClientTest — "maps every build status to the documented Gitea state"](../../src/test/kotlin/de/hoennig/gittally/gitea/GiteaClientTest.kt)
|
||||
- [GiteaStateMappingTest](../../src/test/kotlin/de/hoennig/werkator/gitea/GiteaStateMappingTest.kt)
|
||||
- [GiteaClientTest — "maps every build status to the documented Gitea state"](../../src/test/kotlin/de/hoennig/werkator/gitea/GiteaClientTest.kt)
|
||||
|
||||
## The Solution
|
||||
|
||||
|
||||
@@ -34,7 +34,7 @@ So that the cleanup is part of every GitTally installation instead of a manual s
|
||||
|
||||
##### Verified by
|
||||
|
||||
- [InitCommandTest — "--systemd also generates the nightly Docker cleanup timer"](../../src/test/kotlin/de/hoennig/gittally/commands/InitCommandTest.kt)
|
||||
- [InitCommandTest — "--systemd also generates the nightly Docker cleanup timer"](../../src/test/kotlin/de/hoennig/werkator/commands/InitCommandTest.kt)
|
||||
|
||||
#### Scenario#000.02: The cleanup prunes containers and images but never volumes
|
||||
|
||||
@@ -48,8 +48,8 @@ So that nightly builds start from fresh images while the Gradle caches survive.
|
||||
|
||||
##### Verified by
|
||||
|
||||
- [SystemdServiceFilesTest — "prune service cleans containers and images but never volumes"](../../src/test/kotlin/de/hoennig/gittally/commands/SystemdServiceFilesTest.kt)
|
||||
- [SystemdServiceFilesTest — "prune timer fires nightly at 02:00 and catches up after downtime"](../../src/test/kotlin/de/hoennig/gittally/commands/SystemdServiceFilesTest.kt)
|
||||
- [SystemdServiceFilesTest — "prune service cleans containers and images but never volumes"](../../src/test/kotlin/de/hoennig/werkator/commands/SystemdServiceFilesTest.kt)
|
||||
- [SystemdServiceFilesTest — "prune timer fires nightly at 02:00 and catches up after downtime"](../../src/test/kotlin/de/hoennig/werkator/commands/SystemdServiceFilesTest.kt)
|
||||
|
||||
## The Solution
|
||||
|
||||
|
||||
@@ -0,0 +1,189 @@
|
||||
> **WARNING:** This document describes only the change applied in this PR.
|
||||
> It may already be outdated once the next PR is merged.
|
||||
> Historic PR-documentation is not maintained along with new PRs — treat it as a snapshot, not as current documentation.
|
||||
|
||||
## The Problem
|
||||
|
||||
`gitTally` is the name of another product in the git space.
|
||||
Sharing it is a risk that is cheap to remove now and expensive to remove later, so the project is renamed to **Werkator** as a precaution.
|
||||
Nothing about what the build system does changes.
|
||||
|
||||
A rename of a CI system is not a search-and-replace, because the name is part of a running installation:
|
||||
|
||||
- The configuration is found by name — `.gittally.yml` and `.git/gittally/.gittally.yml`.
|
||||
- The state is found by path — `.git/gittally/` holds the build history, the control token, the scheduled-build state and the build worktrees.
|
||||
|
||||
Neither is loud when it goes missing.
|
||||
A configuration that is not found leaves every setting at its default, and a state directory that is not found is simply empty.
|
||||
An installation updated without renaming would therefore not fail; it would come up looking healthy, having forgotten its credentials, its addresses, its build history and what it builds.
|
||||
|
||||
The rename must therefore carry existing installations across, not just rename files in this repository.
|
||||
|
||||
## Non-Goals
|
||||
|
||||
- No behavioral change to builds, watching, the API or the web UI.
|
||||
- No rename in the old PR-docs under `docs/prs/` and no rewriting of the historic entries in the release notes: both record what was published at the time.
|
||||
- No automatic migration of anything outside the repository — the artifact root, the systemd units, the runtime bundle, the Docker names and labels and the Gitea check context stay manual, listed in [the migration plan](../werkator-migrationsplan.md).
|
||||
- No permanent dual-name support: the configuration fallback is temporary and goes away once the watched repositories have been renamed.
|
||||
|
||||
## The Scenarios
|
||||
|
||||
### Feature: an installation keeps working across the rename
|
||||
|
||||
#### Background
|
||||
|
||||
- The *committed configuration* is `.werkator.yml` at the repository root, in a build worktree, and as committed on a branch.
|
||||
- The *machine configuration* is `.git/werkator/.werkator.yml` and holds the secrets.
|
||||
- The *state directory* is `.git/werkator/` and holds everything the instance remembers.
|
||||
- *Pre-rename* names are spelled exactly as they were: `.gittally.yml` and `.git/gittally/`.
|
||||
|
||||
#### Scenario#1.01: A configuration under its pre-rename name is still read
|
||||
|
||||
So that an installation may be updated and renamed in two separate steps, at its own pace.
|
||||
|
||||
- **Given** a repository whose committed configuration is named `.gittally.yml`
|
||||
- **and** no `.werkator.yml` next to it
|
||||
- **When** the configuration is loaded
|
||||
- **Then** its settings take effect exactly as under the current name
|
||||
|
||||
##### Verified by
|
||||
|
||||
- [ConfigLoaderTest: "falls back to the pre-rename .gittally.yml at the repository root"](../../src/test/kotlin/de/hoennig/werkator/config/ConfigLoaderTest.kt)
|
||||
- [ConfigLoaderTest: "falls back to the pre-rename machine config under .git/gittally"](../../src/test/kotlin/de/hoennig/werkator/config/ConfigLoaderTest.kt)
|
||||
- [ConfigLoaderTest: "a branch whose config is committed under the pre-rename name is still read as the branch layer"](../../src/test/kotlin/de/hoennig/werkator/config/ConfigLoaderTest.kt)
|
||||
- [WatcherTest: "a branch config committed under the pre-rename name is still read"](../../src/test/kotlin/de/hoennig/werkator/watcher/WatcherTest.kt)
|
||||
|
||||
#### Scenario#1.02: The current name wins, and the old file is not merged
|
||||
|
||||
So that a half-done rename cannot revive a setting somebody deliberately dropped while rewriting.
|
||||
|
||||
- **Given** a repository holding both `.werkator.yml` and `.gittally.yml`
|
||||
- **When** the configuration is loaded
|
||||
- **Then** only `.werkator.yml` is read
|
||||
- **and** keys present only in `.gittally.yml` have no effect
|
||||
|
||||
##### Verified by
|
||||
|
||||
- [ConfigLoaderTest: "the current name wins where both exist, so a half-done rename is not merged"](../../src/test/kotlin/de/hoennig/werkator/config/ConfigLoaderTest.kt)
|
||||
|
||||
#### Scenario#1.03: The state directory moves itself at the first start
|
||||
|
||||
So that an update does not silently cost an installation its build history and its control token.
|
||||
|
||||
- **Given** an installation whose state lives in `.git/gittally/`
|
||||
- **and** no `.git/werkator/` next to it
|
||||
- **When** any Werkator command is started in that repository
|
||||
- **Then** the directory is `.git/werkator/` afterwards, with its contents
|
||||
- **and** the build history and the control token are the ones from before
|
||||
|
||||
##### Verified by
|
||||
|
||||
- [StateDirMigrationTest: "moves the pre-rename state directory to its current path"](../../src/test/kotlin/de/hoennig/werkator/StateDirMigrationTest.kt)
|
||||
|
||||
#### Scenario#1.04: The moved worktrees are dropped rather than repaired
|
||||
|
||||
So that a build worktree pointing at its old path cannot break the next build.
|
||||
|
||||
- **Given** a state directory that is moved and holds build worktrees
|
||||
- **When** the move happens
|
||||
- **Then** the worktrees are gone
|
||||
- **and** the rest of the state survives
|
||||
- **and** the next build of a branch recreates its worktree
|
||||
|
||||
##### Verified by
|
||||
|
||||
- [StateDirMigrationTest: "drops the moved worktrees, because they point at their old path"](../../src/test/kotlin/de/hoennig/werkator/StateDirMigrationTest.kt)
|
||||
|
||||
#### Scenario#1.05: Two state directories are never merged or guessed between
|
||||
|
||||
So that an operator who moved the directory by hand does not lose the live state to an automatism.
|
||||
|
||||
- **Given** an installation holding both `.git/gittally/` and `.git/werkator/`
|
||||
- **When** a command is started
|
||||
- **Then** nothing is moved
|
||||
- **and** a warning names the leftover
|
||||
|
||||
##### Verified by
|
||||
|
||||
- [StateDirMigrationTest: "leaves both alone when the current directory already exists"](../../src/test/kotlin/de/hoennig/werkator/StateDirMigrationTest.kt)
|
||||
- [StateDirMigrationTest: "does nothing where there is no pre-rename directory"](../../src/test/kotlin/de/hoennig/werkator/StateDirMigrationTest.kt)
|
||||
|
||||
#### Scenario#1.06: The machine configuration survives a directory that moved without it
|
||||
|
||||
So that the move cannot produce a pair of names its own lookup does not expect.
|
||||
|
||||
- **Given** a state directory that has moved to `.git/werkator/`
|
||||
- **and** the machine configuration inside it still named `.gittally.yml`
|
||||
- **When** the configuration is loaded
|
||||
- **Then** its settings take effect
|
||||
- **and** where the move did it, the file carries the current name afterwards
|
||||
|
||||
##### Verified by
|
||||
|
||||
- [StateDirMigrationTest: "renames the machine configuration inside the moved directory"](../../src/test/kotlin/de/hoennig/werkator/StateDirMigrationTest.kt)
|
||||
- [StateDirMigrationTest: "never overwrites a machine configuration that already carries the current name"](../../src/test/kotlin/de/hoennig/werkator/StateDirMigrationTest.kt)
|
||||
- [ConfigLoaderTest: "finds the machine config left under its old name in an already-moved directory"](../../src/test/kotlin/de/hoennig/werkator/config/ConfigLoaderTest.kt)
|
||||
|
||||
## The Solution
|
||||
|
||||
**One spelling rule.**
|
||||
`Werkator` where the name is prose, capitalized where it is a Kotlin type and the file holding it, lowercase everywhere a machine reads it — the command, the packages, paths, configuration keys and values, the Gitea check context.
|
||||
Environment variables keep their own convention and are uppercase throughout.
|
||||
This is what turns a rename into a decidable question instead of a matter of taste, and it is applied across the whole repository, file names included.
|
||||
|
||||
**A name fallback for the configuration, in one place.**
|
||||
[`ConfigFiles`](../../src/main/kotlin/de/hoennig/werkator/config/ConfigFiles.kt) holds the pair of names and is used by all four lookups: the machine and project layers in `ConfigLoader.loadRaw`, the build worktree in `ConfigLoader.loadForWorktree`, the branch layer the watcher reads out of git, and the same read in the web UI.
|
||||
The current name wins and the old file is then ignored rather than merged — two files side by side are a half-done rename, not a layering.
|
||||
Error messages name the file that was actually read, so they never point at a file that does not exist.
|
||||
|
||||
**A move that finishes the job.**
|
||||
The deployment to vm4006 found the gap the hard way: the move renames the *directory* and leaves the file inside it alone, so the machine configuration ended up at `.git/werkator/.gittally.yml` — a pair of names the lookup did not expect.
|
||||
The instance came up with empty credentials and no host build definitions, without an error, which is the failure this PR exists to prevent.
|
||||
`StateDirMigration` now renames the configuration along with the directory, unless one under the current name is already there, and `ConfigFiles` carries the intermediate path as a third candidate for a directory somebody moved by hand.
|
||||
|
||||
The same deployment found the second half of it: `init --systemd` runs `init`, whose "does it already exist" check knew only the current name, so it wrote a fresh template `.werkator.yml` beside the repository's committed `.gittally.yml` — and the current name wins, so the repository would have started building the template's `./gradlew test` instead of what it says it builds.
|
||||
Both checks now ask `ConfigFiles`, which is the same question the loader asks.
|
||||
|
||||
**A one-time move for the state.**
|
||||
[`StateDirMigration`](../../src/main/kotlin/de/hoennig/werkator/StateDirMigration.kt) renames `.git/gittally` to `.git/werkator` from `CliRunner`, before any command resolves a path under it and therefore before the second Spring context of `server` exists.
|
||||
A fallback was rejected here: unlike a configuration, the state is written, so a fallback would have to decide on every write which of two directories wins, where a one-time move decides once and leaves a single path behind.
|
||||
The move is deliberately narrow — only when the old directory exists and the new one does not — and a failure is an error in the log, never an abort, because a CI must not hang on it.
|
||||
|
||||
**A round number for the new name.**
|
||||
The release after `0.9.21` is `1.0.0`, and the release note says why: a product that changes its name is better off counting from one under it.
|
||||
It is deliberately not a claim about maturity — plan steps 14, 17 and 18 are open.
|
||||
|
||||
**A plan for what cannot be automated.**
|
||||
[`docs/werkator-migrationsplan.md`](../werkator-migrationsplan.md) lists the artifact root, the systemd units, the Docker names and labels, the runtime bundle, the managed nginx container and the Gitea check context, with the order of work, the verification and the rollback.
|
||||
The rollback section names the asymmetry: the new version reads both names, the old one only the old, so a rollback works only while the configuration files still carry their pre-rename names.
|
||||
|
||||
## Open Questions
|
||||
|
||||
- **Decided: lowercase.** The default `gitea.statusContext` is `werkator`.
|
||||
It was worth asking, because it is the one value a human reads as a label, in Gitea next to the commit.
|
||||
It stays lowercase because it is also matched by Gitea and read back by the client, which makes it a value, not prose.
|
||||
|
||||
## Additional Changes
|
||||
|
||||
- Deleted `docs/migration-from-legacy.md`.
|
||||
It mapped the legacy bash script's environment variables to YAML keys, and every host it addressed has migrated.
|
||||
Its removal also settles one open item of [plan step 18](../plan/18-remove-branches-section.md).
|
||||
- Fixed a broken web UI: five templates already referenced `/werkator.js` and `/werkator.css` while the static files were still named `gittally.*`, so every page but the release notes served neither stylesheet nor live updates.
|
||||
- Renamed the Kotlin types `werkatorCommand` and `werkatorMeta`, which a case-insensitive replace had left lowercase, and the constant `werkator_LABEL` to `WERKATOR_LABEL`.
|
||||
- Added the release-notes entry for the rename, as `unreleased`.
|
||||
- Removed the legacy environment-variable conversion from `tools/setup-werkator-instance`.
|
||||
The blanket rename had rewritten the old script's `GITTALLY_*` variables to a spelling that never existed on any host, so the conversion would have read nothing from a real legacy file and written an almost empty configuration — silently.
|
||||
The conversion has served its purpose with the vm2176 → vm4006 migration; what remains is the setup of a new instance: the preconditions, the credential prompt, and the machine configuration written mode 600.
|
||||
It also stops emitting a legacy `branches:` section, which [plan step 18](../plan/18-remove-branches-section.md) is about to reject outright.
|
||||
- Restored the real `GITTALLY_*` spelling in `docs/plan/00-legacy-analysis.md` and `docs/plan/13-nginx-tls.md`, which record what the old script read.
|
||||
- Left the pre-rename fallback out of the release notes and `docs/configuration.md`.
|
||||
Exactly one repository carries the old names and it is migrated by hand in the same move as this release, so the fallback is a transition of days rather than something to plan around.
|
||||
It stays described where it is worked on: in `ConfigFiles`, in `StateDirMigration`, and in the migration plan.
|
||||
- Migrated this repository's own `.werkator.yml` from the deprecated `branches` section to a `builds.default` definition with a `trigger` block.
|
||||
Nothing about its build changes; it stops being the blocker for the precondition of [plan step 18](../plan/18-remove-branches-section.md), which requires that no configuration still in play carries the section, and which rejects it by name afterwards.
|
||||
|
||||
## Follow-up PRs
|
||||
|
||||
- Set the version and the release date, and deploy to vm4006 following the migration plan.
|
||||
- Change `gitea.statusContext` in the watched repository `hs.hsadmin.ng`, where `origin/master` still sets `GitTally`, together with the branch protection rule that names the check.
|
||||
- Remove the configuration name fallback once the watched repositories carry the current names, and reject a leftover `.gittally.yml` by name — the same reasoning as for the legacy `branches` section in [plan step 18](../plan/18-remove-branches-section.md).
|
||||
@@ -0,0 +1,213 @@
|
||||
# Migration Plan: GitTally → Werkator
|
||||
|
||||
The rename is a precaution: `gitTally` is the name of another product in the git space.
|
||||
Nothing about what the build system does changes, but the name is part of a running installation in more places than the configuration.
|
||||
This document lists every one of them, says which are handled automatically, and gives the order in which the rest is done.
|
||||
|
||||
Read [deployment.md](deployment.md) for the deployment itself; this plan only covers what the rename adds to it.
|
||||
|
||||
## What Is Handled Automatically
|
||||
|
||||
Every configuration file is looked up under its current name first and under the pre-rename name second, spelled exactly as it was (`config/ConfigFiles.kt`):
|
||||
|
||||
| Layer | current | still accepted |
|
||||
|---|---|---|
|
||||
| Machine config | `.git/werkator/.werkator.yml` | `.git/gittally/.gittally.yml` |
|
||||
| Project config | `.werkator.yml` | `.gittally.yml` |
|
||||
| Branch config, in a build worktree | `.werkator.yml` | `.gittally.yml` |
|
||||
| Branch config, read out of git | `<commit>:.werkator.yml` | `<commit>:.gittally.yml` |
|
||||
|
||||
The current name wins where both exist, and the old file is then ignored rather than merged.
|
||||
Two files side by side are a half-done rename, not a layering — merging them would revive a setting somebody deliberately dropped while rewriting.
|
||||
|
||||
The fallback exists because a configuration that is not found is not an error.
|
||||
It leaves every setting at its default, so an installation that updated without renaming would come up looking healthy while having forgotten its credentials, its addresses, and what it builds.
|
||||
|
||||
The fallback is temporary and goes away once the watched repositories have been renamed.
|
||||
|
||||
## What Else the Rename Touches
|
||||
|
||||
### 1. The state directory — done automatically
|
||||
|
||||
`.git/gittally/` → `.git/werkator/`, with everything in it:
|
||||
|
||||
- the machine configuration (found under either name, but it belongs next to the rest)
|
||||
- `build-results.json` — the entire build history
|
||||
- `auto-builds.json` — which scheduled slots already fired today
|
||||
- `control-token` — the token that authorizes mutating API calls
|
||||
- `worktrees/<branchKey>/` — the per-branch build worktrees
|
||||
- the generated systemd unit and its `EnvironmentFile`
|
||||
|
||||
There is no name fallback for this path, so the first start after the update moves it (`StateDirMigration`).
|
||||
Without the move the instance would start with an empty history, a fresh control token, and no memory of today's scheduled builds — again without a single failure, which is why it is done rather than documented.
|
||||
|
||||
The move happens only when the old directory exists and the new one does not.
|
||||
Where both exist, nothing is moved and a warning names the leftover: which of the two is the live state is not something to guess.
|
||||
A move that fails is logged as an error and does not stop the start.
|
||||
|
||||
Two things follow from the move, both handled or reported:
|
||||
|
||||
- The worktrees hold absolute paths in both directions (`.git/worktrees/<name>/gitdir` and the worktree's own `.git` file), so they are dropped instead of repaired.
|
||||
Each is recreated by its branch's next build, which prunes the stale admin entry first.
|
||||
- The generated systemd unit moves with the directory, which leaves its symlink in `~/.config/systemd/user` dangling — the running service is unaffected, the next start is not.
|
||||
A warning names the unit; re-run `werkator init --systemd` and re-link it, see step 3.
|
||||
|
||||
### 2. The artifact root
|
||||
|
||||
Unless `artifacts.rootDir` is set explicitly, artifacts live under `$XDG_STATE_HOME/werkator/artifacts/<repoKey>`, in practice `~/.local/state/werkator/artifacts/<repoKey>`.
|
||||
Move `~/.local/state/gittally/` to `~/.local/state/werkator/`.
|
||||
Left behind, the stored logs and reports of every past build are unreachable, and the permanent latest-green links point at nothing.
|
||||
|
||||
### 3. The systemd units
|
||||
|
||||
The unit names carry the product name:
|
||||
|
||||
| current | before |
|
||||
|---|---|
|
||||
| `werkator-<repo>.service` | `gittally-<repo>.service` |
|
||||
| `werkator.env` | `gittally.env` |
|
||||
| `werkator-docker-prune.service` / `.timer` | `gittally-docker-prune.service` / `.timer` |
|
||||
|
||||
The symlinks in `~/.config/systemd/user/` point into the state directory, so moving that directory breaks them.
|
||||
Disable and remove the old units, regenerate with `werkator init --systemd`, then enable the new ones.
|
||||
The prune units are host-global and shared by all instances on the host — replace them once, not per repository.
|
||||
|
||||
### 4. Docker names and labels
|
||||
|
||||
| what | current | before |
|
||||
|---|---|---|
|
||||
| build container | `werkator-build-<repoKey>-<branchKey>` | `gittally-build-…` |
|
||||
| Gradle cache volume | `werkator-gradle-<repoKey>` | `gittally-gradle-…` |
|
||||
| container label | `org.hoennig.werkator` | `org.hoennig.gittally` |
|
||||
| image input label | `org.werkator.build-inputs-sha256` | `org.gittally.…` |
|
||||
|
||||
The consequences are all one-off and none of them is fatal:
|
||||
|
||||
- A new Gradle cache volume is empty, so the first build after the rename is slow. Rename the volume beforehand if that matters, or accept one cold build.
|
||||
- The changed image label makes the build image rebuild once.
|
||||
- Stale containers from before the rename carry the old label, so the cleanup on restart does not see them. Remove them once by hand.
|
||||
|
||||
### 5. The Gitea check
|
||||
|
||||
`gitea.statusContext` is the name the check appears under in Gitea; the default is now `werkator`.
|
||||
Gitea itself needs no preparation — the context is created implicitly by the first status posted.
|
||||
But a branch protection rule that requires the old context will never be satisfied again, and pull requests wait forever for a check nobody posts.
|
||||
Update the rule in the same step, or leave `statusContext` at the old value until it is.
|
||||
|
||||
Statuses already written keep their old context, so a commit built before and after the change shows both.
|
||||
Werkator also reads the newest status matching the configured context, so the first build after the switch does not see its own earlier results — harmless, at most one extra build.
|
||||
|
||||
### 6. The runtime bundle
|
||||
|
||||
On hosts without a Java runtime the bundle unpacks to `~/opt/werkator/` and its launcher is named `werkator`.
|
||||
Move `~/opt/gittally/` accordingly, or unpack the new bundle fresh and remove the old directory once the service runs.
|
||||
|
||||
### 7. The managed nginx container
|
||||
|
||||
Only where `server.nginx.enabled` is set.
|
||||
The container defaults to `werkator-nginx-<repo>` and its state (certificates included) to `~/.local/state/werkator/nginx/`.
|
||||
Move the state directory with the artifact root, and remove the old container so the new one can take the ports.
|
||||
|
||||
## Order of Work
|
||||
|
||||
Per installation, and only while `/api/builds/current` is `[]` — a running build is interrupted by the restart and re-enqueued, but there is no reason to force that.
|
||||
|
||||
1. `systemctl --user stop werkator-<repo>.service` (old name).
|
||||
2. Move the artifact root and the bundle; the state directory moves itself at the first start.
|
||||
3. Rename the configuration files at the same time, or leave them to the fallback.
|
||||
4. Deploy the new version and start it once, so the state directory moves.
|
||||
5. `werkator init --systemd`, disable the old units, enable the new ones.
|
||||
6. Start the service.
|
||||
7. Update the Gitea branch protection rule if it names the check.
|
||||
|
||||
## Verification
|
||||
|
||||
- `werkator config:print --full` before the restart: every definition resolves completely, the credentials are there, the docker settings are the host's.
|
||||
- After the start: the build history is the one from before, the watcher polls without errors, no warning about a configuration that was not found.
|
||||
- A branch build starts, runs in the expected image, and reports under the expected Gitea check.
|
||||
|
||||
## Rollback
|
||||
|
||||
Keep the previous bundle and a timestamped copy of the machine configuration.
|
||||
Note the asymmetry: the new version reads both names, the old one only reads the old name.
|
||||
So a rollback works as long as the configuration files still carry — or carry again — their pre-rename names.
|
||||
The state directory has to be moved back by hand; nothing moves it in that direction.
|
||||
|
||||
## Open Points
|
||||
|
||||
- **Settled:** the state directory is moved at the first start instead of getting a name fallback.
|
||||
A fallback would have to decide, on every write, which of two directories wins; a one-time move decides once and leaves one path afterwards.
|
||||
- **This repository's own file names** are a separate step: 121 paths still contain `gittally`, package directories included.
|
||||
The rename script for it is written and waits.
|
||||
- **When the fallback goes away**, `ConfigFiles` loses its legacy entries and a leftover `.gittally.yml` should be rejected by name rather than ignored — the same reasoning as for the legacy `branches` section in [plan step 18](plan/18-remove-branches-section.md).
|
||||
|
||||
## Per Host
|
||||
|
||||
### vm4006, `hs.hsadmin.ng`
|
||||
|
||||
#### The v1.0.0 deployment, in place and revertible
|
||||
|
||||
Measured on 2026-08-31: the state directory is 878 MB, of which 878 MB are the nine build worktrees.
|
||||
Everything that cannot be recreated — build history, control token, machine configuration, auto-build state, the generated systemd files — is **84 KB**.
|
||||
That is what makes an in-place switch safe: the snapshot is instant, and the worktrees are dropped by the migration and recreated per branch by the next build.
|
||||
|
||||
Precondition: `curl -s http://127.0.0.1:18080/api/builds/current` answers `[]`.
|
||||
|
||||
```bash
|
||||
# 1. from the branch, locally
|
||||
./gradlew runtimeBundle
|
||||
scp build/distributions/werkator-runtime-linux-x64.tar.gz tallyman@vm4006.hostsharing.net:~/
|
||||
|
||||
# 2. stop, then snapshot the 84 KB that matter
|
||||
systemctl --user stop gittally-hs.hsadmin.ng.service
|
||||
STAMP=$(date -u +%Y%m%dT%H%M%SZ)
|
||||
tar czf ~/gittally-state-$STAMP.tar.gz -C ~/hs.hsadmin.ng/.git --exclude=gittally/worktrees gittally
|
||||
|
||||
# 3. bundle beside the old one, following the existing convention
|
||||
mv ~/opt/gittally ~/opt/gittally.0.9.21.bak
|
||||
tar xzf ~/werkator-runtime-linux-x64.tar.gz -C ~/opt
|
||||
|
||||
# 4. artifact root: a move on the same filesystem, instant in both directions
|
||||
mv ~/.local/state/gittally ~/.local/state/werkator
|
||||
|
||||
# 5. let the state directory move itself, and read what it says.
|
||||
# Check the output: publicBaseUrl, git.account and the host's build
|
||||
# definitions must be there. Empty ones mean the machine configuration
|
||||
# was not found — nothing fails on its own in that case.
|
||||
cd ~/hs.hsadmin.ng
|
||||
~/opt/werkator/jre/bin/java -jar ~/opt/werkator/lib/werkator.jar config:print --full
|
||||
|
||||
# 6. units
|
||||
systemctl --user disable --now gittally-hs.hsadmin.ng.service gittally-docker-prune.timer
|
||||
rm -f ~/.config/systemd/user/gittally-*
|
||||
~/opt/werkator/jre/bin/java -jar ~/opt/werkator/lib/werkator.jar init --systemd
|
||||
# follow the ln -s / daemon-reload / enable commands it prints
|
||||
```
|
||||
|
||||
Verification, in this order: the service is `active`, the web UI footer reads `Werkator v1.0.0`, the build history is the one from before, `/api/builds/current` answers, the watcher polls without errors in the journal, and a real branch build runs in `hsadmin-ng-build-env:latest` and reports to Gitea.
|
||||
|
||||
Rollback, one sequence, about a minute:
|
||||
|
||||
```bash
|
||||
systemctl --user disable --now werkator-hs.hsadmin.ng.service werkator-docker-prune.timer
|
||||
rm -f ~/.config/systemd/user/werkator-*
|
||||
rm -rf ~/hs.hsadmin.ng/.git/werkator
|
||||
tar xzf ~/gittally-state-$STAMP.tar.gz -C ~/hs.hsadmin.ng/.git
|
||||
mv ~/.local/state/werkator ~/.local/state/gittally
|
||||
rm -rf ~/opt/werkator && mv ~/opt/gittally.0.9.21.bak ~/opt/gittally
|
||||
systemctl --user daemon-reload
|
||||
systemctl --user enable --now gittally-hs.hsadmin.ng.service gittally-docker-prune.timer
|
||||
```
|
||||
|
||||
Three things are expected and are not failures:
|
||||
|
||||
- The first build after the switch is slower: the Gradle cache volume is keyed by name, so `werkator-gradle-<repoKey>` starts empty while `gittally-gradle-<repoKey>` keeps its content for a rollback.
|
||||
- The build image is rebuilt once, because the label carrying its input hash changed.
|
||||
- Containers left from before carry the old label, so the cleanup on restart does not see them; remove them by hand once the deployment stands.
|
||||
|
||||
`gitea.statusContext` needs no attention here: it comes from master's committed configuration in the watched repository, which still says `GitTally`, so the Gitea checks and any branch protection rule keep working untouched.
|
||||
|
||||
- The machine configuration is `~/hs.hsadmin.ng/.git/gittally/.gittally.yml`, mode 600, and it holds the Gitea token — check the mode after every edit, a shell redirect creates 644.
|
||||
- The committed configuration on master still sets `statusContext: GitTally`; it changes with the merge that also renames the file, and that merge needs a colleague's approval.
|
||||
- Deploy only while `/api/builds/current` is `[]`.
|
||||
- Keep the timestamped backups of the machine configuration that already exist next to it.
|
||||
@@ -1,176 +0,0 @@
|
||||
# Environment for GitTally
|
||||
#
|
||||
# Save and source this output before starting the script, for example:
|
||||
# gitTally --env > .gittally.env
|
||||
# . .gittally.env
|
||||
|
||||
# ================================================================================
|
||||
# Installation
|
||||
# --------------------------------------------------------------------------------
|
||||
|
||||
# Target directory used by --install.
|
||||
# default GITTALLY_INSTALL_DIR=$HOME/bin
|
||||
export GITTALLY_INSTALL_DIR=$HOME/gitTally
|
||||
|
||||
# ================================================================================
|
||||
# Build command
|
||||
# --------------------------------------------------------------------------------
|
||||
|
||||
# Shell command executed for each build. The branch name is available as $branch.
|
||||
# default GITTALLY_BUILD_COMMAND='./gradlew --console=plain --no-daemon --no-build-cache --rerun-tasks test'
|
||||
export GITTALLY_BUILD_COMMAND='./gradlew --console=plain --no-daemon --no-build-cache --rerun-tasks migrationTest -x unitTest -x test -x check -x pitest -x dependencyCheckAnalyze'
|
||||
|
||||
# Shell command executed before a non-Docker build and before preparing a Docker workspace.
|
||||
# default GITTALLY_BUILD_CLEAN_COMMAND='rm -rf build'
|
||||
export GITTALLY_BUILD_CLEAN_COMMAND='rm -rf build'
|
||||
|
||||
# Report directories copied into artifacts. Separate multiple paths with ';'.
|
||||
# default GITTALLY_BUILD_ARTEFACT_DIRS='build/reports'
|
||||
export GITTALLY_BUILD_ARTEFACT_DIRS='build/reports;build/doc'
|
||||
|
||||
# Artifact filename for captured build stdout.
|
||||
# default GITTALLY_BUILD_STDOUT_LOG='build.stdout.log'
|
||||
export GITTALLY_BUILD_STDOUT_LOG='build.stdout.log'
|
||||
|
||||
# Artifact filename for captured build stderr.
|
||||
# default GITTALLY_BUILD_STDERR_LOG='build.stderr.log'
|
||||
export GITTALLY_BUILD_STDERR_LOG='build.stderr.log'
|
||||
|
||||
# Maximum age for the latest commit on new origin branches. Use h/d suffix.
|
||||
# default GITTALLY_NEW_BRANCH_COMMIT_MAX_AGE='3d'
|
||||
# export GITTALLY_NEW_BRANCH_COMMIT_MAX_AGE='3d'
|
||||
|
||||
# ================================================================================
|
||||
# Docker build runtime
|
||||
# --------------------------------------------------------------------------------
|
||||
|
||||
# Docker image used when --docker is enabled.
|
||||
# default GITTALLY_BUILD_DOCKER_IMAGE='hsadmin-ng-build-env:latest'
|
||||
export GITTALLY_BUILD_DOCKER_IMAGE='hsadmin-ng-build-env:latest'
|
||||
|
||||
# Dockerfile used to build the image when it does not exist locally.
|
||||
# default GITTALLY_BUILD_DOCKERFILE='Jenkins/jenkins-agent/Dockerfile'
|
||||
export GITTALLY_BUILD_DOCKERFILE='Jenkins/jenkins-agent/Dockerfile'
|
||||
|
||||
# Docker build context used with GITTALLY_BUILD_DOCKERFILE.
|
||||
# default GITTALLY_BUILD_DOCKER_CONTEXT='Jenkins/jenkins-agent'
|
||||
export GITTALLY_BUILD_DOCKER_CONTEXT='Jenkins/jenkins-agent'
|
||||
|
||||
# Docker network mode for build containers.
|
||||
# default GITTALLY_BUILD_DOCKER_NETWORK='host'
|
||||
export GITTALLY_BUILD_DOCKER_NETWORK='host'
|
||||
|
||||
# Command run inside the build container to verify Docker access.
|
||||
# default GITTALLY_BUILD_DOCKER_PREFLIGHT_COMMAND='docker version'
|
||||
export GITTALLY_BUILD_DOCKER_PREFLIGHT_COMMAND='docker version'
|
||||
|
||||
# Additional environment assignments passed to the build container, separated by spaces.
|
||||
# default GITTALLY_BUILD_DOCKER_ENV='TESTCONTAINERS_RYUK_DISABLED=true'
|
||||
export GITTALLY_BUILD_DOCKER_ENV='TESTCONTAINERS_RYUK_DISABLED=true'
|
||||
|
||||
# Java tool options added for Docker and Testcontainers defaults.
|
||||
# default GITTALLY_BUILD_DOCKER_JAVA_TOOL_OPTIONS='-Ddocker.client.strategy=org.testcontainers.dockerclient.UnixSocketClientProviderStrategy -Dtestcontainers.docker.socket.override=/var/run/docker.sock'
|
||||
export GITTALLY_BUILD_DOCKER_JAVA_TOOL_OPTIONS='-Ddocker.client.strategy=org.testcontainers.dockerclient.UnixSocketClientProviderStrategy -Dtestcontainers.docker.socket.override=/var/run/docker.sock'
|
||||
|
||||
# ================================================================================
|
||||
# Artifact server
|
||||
# --------------------------------------------------------------------------------
|
||||
|
||||
# Preferred HTTP port for serving archived build artifacts.
|
||||
# default GITTALLY_ARTIFACT_SERVER_PORT='18080'
|
||||
export GITTALLY_ARTIFACT_SERVER_PORT='18080'
|
||||
|
||||
# Bind address for the artifact HTTP server.
|
||||
# default GITTALLY_ARTIFACT_SERVER_BIND_ADDRESS='0.0.0.0'
|
||||
export GITTALLY_ARTIFACT_SERVER_BIND_ADDRESS='0.0.0.0'
|
||||
|
||||
|
||||
# Public base URL used for artifact links and Gitea status target URLs.
|
||||
# default GITTALLY_ARTIFACT_PUBLIC_BASE_URL='https://ci.example.org/'
|
||||
export GITTALLY_ARTIFACT_PUBLIC_BASE_URL='https://vm2176.hostsharing.net/'
|
||||
|
||||
# Retained builds per branch. Use a count, or h/d suffix for age based retention.
|
||||
# default GITTALLY_ARTIFACT_BUILD_RETENTION_PER_BRANCH='3'
|
||||
export GITTALLY_ARTIFACT_BUILD_RETENTION_PER_BRANCH='3'
|
||||
|
||||
# ================================================================================
|
||||
# Nginx and certificates
|
||||
# --------------------------------------------------------------------------------
|
||||
|
||||
# Public server name for the nginx and certificate setup.
|
||||
# default GITTALLY_ARTIFACT_NGINX_SERVER_NAME='ci.example.org'
|
||||
export GITTALLY_ARTIFACT_NGINX_SERVER_NAME='vm2176.hostsharing.net'
|
||||
|
||||
# Host HTTP port published by the nginx container.
|
||||
# default GITTALLY_ARTIFACT_NGINX_HTTP_PORT='8080'
|
||||
export GITTALLY_ARTIFACT_NGINX_HTTP_PORT='8080'
|
||||
|
||||
# Host HTTPS port published by the nginx container.
|
||||
# default GITTALLY_ARTIFACT_NGINX_HTTPS_PORT='8443'
|
||||
export GITTALLY_ARTIFACT_NGINX_HTTPS_PORT='8443'
|
||||
|
||||
# Host name nginx uses to reach the artifact HTTP server.
|
||||
# default GITTALLY_ARTIFACT_NGINX_UPSTREAM_HOST='ci.example.org'
|
||||
export GITTALLY_ARTIFACT_NGINX_UPSTREAM_HOST='vm2176.hostsharing.net'
|
||||
|
||||
# Docker container name for the nginx reverse proxy.
|
||||
# default GITTALLY_ARTIFACT_NGINX_CONTAINER_NAME='gittally-nginx-example-repo'
|
||||
export GITTALLY_ARTIFACT_NGINX_CONTAINER_NAME='gittally-nginx-hsadmin-ng'
|
||||
|
||||
# Persistent state directory for nginx config, logs, and certificate data.
|
||||
# default GITTALLY_ARTIFACT_NGINX_STATE_DIR=${XDG_STATE_HOME:-$HOME/.local/state}/gittally/nginx/<repo-key>
|
||||
# export GITTALLY_ARTIFACT_NGINX_STATE_DIR=''
|
||||
|
||||
# Email address used when registering Lets Encrypt certificates.
|
||||
# default GITTALLY_ARTIFACT_LETSENCRYPT_EMAIL='admin@example.org'
|
||||
export GITTALLY_ARTIFACT_LETSENCRYPT_EMAIL=''
|
||||
|
||||
|
||||
# ================================================================================
|
||||
# Legal
|
||||
# --------------------------------------------------------------------------------
|
||||
|
||||
# URL for the Impressum (Legal Disclosure) link in the footer.
|
||||
# default GITTALLY_IMPRESSUM_URL='https://example.org/imprint.html'
|
||||
export GITTALLY_IMPRESSUM_URL='https://michael.hoennig.de/imprint.html'
|
||||
|
||||
# ================================================================================
|
||||
# Auto builds
|
||||
# --------------------------------------------------------------------------------
|
||||
|
||||
# Colon-separated list of branches to rebuild automatically. Leave empty to disable auto builds.
|
||||
# default GITTALLY_AUTO_BUILD_BRANCHES=''
|
||||
export GITTALLY_AUTO_BUILD_BRANCHES='master;main;mihoe/introduce-gitTally-ci'
|
||||
|
||||
# Semicolon-separated list of UTC times (HH:MM) at which auto builds are triggered, e.g. 02:00:08:00:14:00:20:00.
|
||||
# default GITTALLY_AUTO_BUILD_TIMES='02:00'
|
||||
export GITTALLY_AUTO_BUILD_TIMES='03:30'
|
||||
|
||||
# ================================================================================
|
||||
# Gitea
|
||||
# --------------------------------------------------------------------------------
|
||||
|
||||
# Base URL of the Gitea instance.
|
||||
# default GITTALLY_GITEA_BASE_URL='https://git.example.org'
|
||||
export GITTALLY_GITEA_BASE_URL='https://dev.hostsharing.net'
|
||||
|
||||
# Gitea repository owner.
|
||||
# default GITTALLY_GITEA_OWNER='example-owner'
|
||||
export GITTALLY_GITEA_OWNER='hostsharing'
|
||||
|
||||
# Gitea repository name.
|
||||
# default GITTALLY_GITEA_REPO='example-repo'
|
||||
export GITTALLY_GITEA_REPO='hs.hsadmin.ng'
|
||||
|
||||
# Required HTTPS git username used with the Gitea token.
|
||||
# default GITTALLY_GITEA_GIT_USERNAME='example-user'
|
||||
# export GITTALLY_GITEA_GIT_USERNAME='<put-your-gitea-username-here>'
|
||||
|
||||
# Required token used for Gitea commit statuses and HTTPS git authentication.
|
||||
# default GITTALLY_GITEA_TOKEN='<the-users-token-goes-here>'
|
||||
# export GITTALLY_GITEA_TOKEN='<this-secret-will-be-set-in-the-target-environment>'
|
||||
|
||||
# Gitea commit status context published by GitTally.
|
||||
# default GITTALLY_GITEA_STATUS_CONTEXT='GitTally'
|
||||
export GITTALLY_GITEA_STATUS_CONTEXT='GitTally'
|
||||
|
||||
-5970
File diff suppressed because it is too large
Load Diff
@@ -1,6 +1,6 @@
|
||||
#!/bin/sh
|
||||
# Launcher for the self-contained GitTally runtime bundle (jlink JRE + jar).
|
||||
# Launcher for the self-contained Werkator runtime bundle (jlink JRE + jar).
|
||||
# Built by `./gradlew runtimeBundle`; see docs/deployment.md.
|
||||
DIR=$(CDPATH='' cd -- "$(dirname -- "$(readlink -f -- "$0")")" && pwd)
|
||||
# shellcheck disable=SC2086 # JAVA_OPTS is intentionally word-split
|
||||
exec "$DIR/../jre/bin/java" $JAVA_OPTS -jar "$DIR/../lib/gittally.jar" "$@"
|
||||
exec "$DIR/../jre/bin/java" $JAVA_OPTS -jar "$DIR/../lib/werkator.jar" "$@"
|
||||
+1
-1
@@ -1 +1 @@
|
||||
rootProject.name = "gittally"
|
||||
rootProject.name = "werkator"
|
||||
|
||||
+2
-2
@@ -1,4 +1,4 @@
|
||||
package de.hoennig.gittally
|
||||
package de.hoennig.werkator
|
||||
|
||||
import java.nio.ByteBuffer
|
||||
import java.nio.file.Files
|
||||
@@ -8,7 +8,7 @@ import java.nio.file.attribute.PosixFilePermissions
|
||||
|
||||
/**
|
||||
* Creation of files and directories that hold secrets — the Gitea token in
|
||||
* `.git/gittally/.gittally.yml` and the control token.
|
||||
* `.git/werkator/.werkator.yml` and the control token.
|
||||
*
|
||||
* The permissions are set *at creation*, never with a `chmod` after the write:
|
||||
* writing at the umask default first (typically `0644`) would leave a window in
|
||||
@@ -0,0 +1,103 @@
|
||||
package de.hoennig.werkator
|
||||
|
||||
import de.hoennig.werkator.config.ConfigFiles
|
||||
import org.slf4j.LoggerFactory
|
||||
import java.io.IOException
|
||||
import java.nio.file.Files
|
||||
import java.nio.file.Path
|
||||
|
||||
/**
|
||||
* Moves the state directory of an installation that predates the rename to Werkator,
|
||||
* once, at the first start after the update.
|
||||
*
|
||||
* The configuration is found under either name ([de.hoennig.werkator.config.ConfigFiles]),
|
||||
* but the state is not: build history, the control token, the auto-build slots and the
|
||||
* build worktrees live at one fixed path. A missing state directory is as quiet as a
|
||||
* missing configuration — the instance would come up with an empty history and a fresh
|
||||
* control token, and nothing would fail. So this is done rather than documented.
|
||||
*/
|
||||
object StateDirMigration {
|
||||
const val DIR = ".git/werkator"
|
||||
|
||||
private const val LEGACY_DIR = ".git/gittally"
|
||||
private const val WORKTREES = "worktrees"
|
||||
|
||||
private val log = LoggerFactory.getLogger(StateDirMigration::class.java)
|
||||
|
||||
/**
|
||||
* Renames `.git/gittally` to `.git/werkator` in [workingDir], if the first exists and
|
||||
* the second does not. Never throws: a failed move must not stop a CI, it must say
|
||||
* what to do by hand.
|
||||
*/
|
||||
fun migrateIfNeeded(workingDir: Path) {
|
||||
val legacy = workingDir.resolve(LEGACY_DIR)
|
||||
val current = workingDir.resolve(DIR)
|
||||
if (!Files.isDirectory(legacy)) return
|
||||
if (Files.exists(current)) {
|
||||
// both exist: which of the two is the live state is not ours to guess
|
||||
log.warn("{} exists next to {} — the leftover is ignored, remove it once you are sure", LEGACY_DIR, DIR)
|
||||
return
|
||||
}
|
||||
try {
|
||||
Files.move(legacy, current)
|
||||
} catch (e: IOException) {
|
||||
log.error("could not move {} to {}: {} — move it by hand", LEGACY_DIR, DIR, e.message)
|
||||
return
|
||||
}
|
||||
log.info("moved {} to {}: build history, control token and configuration kept", LEGACY_DIR, DIR)
|
||||
renameMachineConfig(current)
|
||||
dropWorktrees(current)
|
||||
warnAboutUnits(current)
|
||||
}
|
||||
|
||||
/**
|
||||
* Moving the directory leaves the file inside it under its old name, and the pair
|
||||
* of names is then one the lookup does not expect. Renaming it here is what makes
|
||||
* the move complete instead of half-done.
|
||||
*/
|
||||
private fun renameMachineConfig(stateDir: Path) {
|
||||
val legacy = stateDir.resolve(ConfigFiles.LEGACY_COMMITTED)
|
||||
val current = stateDir.resolve(ConfigFiles.COMMITTED)
|
||||
if (!Files.isRegularFile(legacy) || Files.exists(current)) return
|
||||
try {
|
||||
Files.move(legacy, current)
|
||||
} catch (e: IOException) {
|
||||
log.warn("could not rename {} to {} in {}: {}", ConfigFiles.LEGACY_COMMITTED, ConfigFiles.COMMITTED, stateDir, e.message)
|
||||
return
|
||||
}
|
||||
log.info("renamed the machine configuration to {}", ConfigFiles.COMMITTED)
|
||||
}
|
||||
|
||||
/**
|
||||
* The moved worktrees point at their old path in both directions, so they are dropped
|
||||
* rather than repaired: the next build of a branch creates its worktree again, and
|
||||
* `GitWorktreeWorkspaces` prunes the stale admin entry before it does.
|
||||
*/
|
||||
private fun dropWorktrees(stateDir: Path) {
|
||||
val worktrees = stateDir.resolve(WORKTREES)
|
||||
if (!Files.isDirectory(worktrees)) return
|
||||
if (worktrees.toFile().deleteRecursively()) {
|
||||
log.info("dropped the moved build worktrees; each is recreated by its branch's next build")
|
||||
} else {
|
||||
log.warn("could not drop the moved build worktrees in {} — delete them by hand", worktrees)
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* The generated systemd unit lives in the state directory and is symlinked from
|
||||
* `~/.config/systemd/user`, so the move leaves that link dangling — the service keeps
|
||||
* running and fails to start the next time.
|
||||
*/
|
||||
private fun warnAboutUnits(stateDir: Path) {
|
||||
val units =
|
||||
Files
|
||||
.list(stateDir)
|
||||
.use { paths -> paths.map { it.fileName.toString() }.filter { it.endsWith(".service") }.toList() }
|
||||
if (units.isEmpty()) return
|
||||
log.warn(
|
||||
"the systemd unit {} moved with the state directory and its symlink now dangles — " +
|
||||
"re-run `werkator init --systemd` and re-link it",
|
||||
units.joinToString(", "),
|
||||
)
|
||||
}
|
||||
}
|
||||
+9
-6
@@ -1,6 +1,6 @@
|
||||
package de.hoennig.gittally
|
||||
package de.hoennig.werkator
|
||||
|
||||
import de.hoennig.gittally.config.ConfigException
|
||||
import de.hoennig.werkator.config.ConfigException
|
||||
import org.springframework.boot.CommandLineRunner
|
||||
import org.springframework.boot.ExitCodeGenerator
|
||||
import org.springframework.boot.SpringApplication
|
||||
@@ -10,26 +10,29 @@ import org.springframework.context.annotation.Profile
|
||||
import org.springframework.stereotype.Component
|
||||
import picocli.CommandLine
|
||||
import picocli.CommandLine.IFactory
|
||||
import java.nio.file.Paths
|
||||
import kotlin.system.exitProcess
|
||||
|
||||
@SpringBootApplication
|
||||
class GitTallyApplication
|
||||
class WerkatorApplication
|
||||
|
||||
/** Not in the `server` profile: the second context started by `ServerCommand` must not run picocli again. */
|
||||
@Component
|
||||
@Profile("!server")
|
||||
class CliRunner(
|
||||
private val factory: IFactory,
|
||||
private val rootCommand: GitTallyCommand,
|
||||
private val rootCommand: WerkatorCommand,
|
||||
) : CommandLineRunner,
|
||||
ExitCodeGenerator {
|
||||
private var exitCode = 0
|
||||
|
||||
override fun run(vararg args: String) {
|
||||
// before any command resolves a path under it, and once per process
|
||||
StateDirMigration.migrateIfNeeded(Paths.get("."))
|
||||
exitCode =
|
||||
CommandLine(rootCommand, factory)
|
||||
.setExecutionExceptionHandler { exception, commandLine, _ ->
|
||||
// a config GitTally must not read is a stated fact, not a crash: the message
|
||||
// a config Werkator must not read is a stated fact, not a crash: the message
|
||||
// names the file, the versions, and the way out — a stack trace would bury it
|
||||
if (exception is ConfigException) {
|
||||
commandLine.err.println("Error: ${exception.message}")
|
||||
@@ -49,5 +52,5 @@ class CliRunner(
|
||||
}
|
||||
|
||||
fun main(args: Array<String>) {
|
||||
exitProcess(SpringApplication.exit(runApplication<GitTallyApplication>(*args)))
|
||||
exitProcess(SpringApplication.exit(runApplication<WerkatorApplication>(*args)))
|
||||
}
|
||||
+10
-10
@@ -1,11 +1,11 @@
|
||||
package de.hoennig.gittally
|
||||
package de.hoennig.werkator
|
||||
|
||||
import de.hoennig.gittally.commands.BuildCommand
|
||||
import de.hoennig.gittally.commands.ConfigPrintCommand
|
||||
import de.hoennig.gittally.commands.InitCommand
|
||||
import de.hoennig.gittally.commands.RetryCommand
|
||||
import de.hoennig.gittally.commands.ServerCommand
|
||||
import de.hoennig.gittally.commands.StatusCommand
|
||||
import de.hoennig.werkator.commands.BuildCommand
|
||||
import de.hoennig.werkator.commands.ConfigPrintCommand
|
||||
import de.hoennig.werkator.commands.InitCommand
|
||||
import de.hoennig.werkator.commands.RetryCommand
|
||||
import de.hoennig.werkator.commands.ServerCommand
|
||||
import de.hoennig.werkator.commands.StatusCommand
|
||||
import org.springframework.beans.factory.ObjectProvider
|
||||
import org.springframework.boot.info.BuildProperties
|
||||
import org.springframework.stereotype.Component
|
||||
@@ -14,7 +14,7 @@ import picocli.CommandLine.Command
|
||||
|
||||
@Component
|
||||
@Command(
|
||||
name = "gittally",
|
||||
name = "werkator",
|
||||
subcommands = [
|
||||
InitCommand::class,
|
||||
ServerCommand::class,
|
||||
@@ -27,7 +27,7 @@ import picocli.CommandLine.Command
|
||||
versionProvider = BuildPropertiesVersionProvider::class,
|
||||
description = ["Lightweight, declarative CI/CD system"],
|
||||
)
|
||||
class GitTallyCommand : Runnable {
|
||||
class WerkatorCommand : Runnable {
|
||||
override fun run(): Unit = throw CommandLine.ParameterException(CommandLine(this), "Specify a subcommand")
|
||||
}
|
||||
|
||||
@@ -41,5 +41,5 @@ class GitTallyCommand : Runnable {
|
||||
class BuildPropertiesVersionProvider(
|
||||
private val buildProperties: ObjectProvider<BuildProperties>,
|
||||
) : CommandLine.IVersionProvider {
|
||||
override fun getVersion(): Array<String> = arrayOf("GitTally v${buildProperties.getIfAvailable()?.version ?: "dev"}")
|
||||
override fun getVersion(): Array<String> = arrayOf("Werkator v${buildProperties.getIfAvailable()?.version ?: "dev"}")
|
||||
}
|
||||
+3
-3
@@ -1,7 +1,7 @@
|
||||
package de.hoennig.gittally.artifacts
|
||||
package de.hoennig.werkator.artifacts
|
||||
|
||||
import de.hoennig.gittally.build.ArtifactStore
|
||||
import de.hoennig.gittally.config.ConfigLoader
|
||||
import de.hoennig.werkator.build.ArtifactStore
|
||||
import de.hoennig.werkator.config.ConfigLoader
|
||||
import org.springframework.context.annotation.Bean
|
||||
import org.springframework.context.annotation.Configuration
|
||||
|
||||
+10
-10
@@ -1,10 +1,10 @@
|
||||
package de.hoennig.gittally.artifacts
|
||||
package de.hoennig.werkator.artifacts
|
||||
|
||||
import de.hoennig.gittally.build.ArtifactKeys
|
||||
import de.hoennig.gittally.build.ArtifactStore
|
||||
import de.hoennig.gittally.build.BuildResult
|
||||
import de.hoennig.gittally.config.BranchConfig
|
||||
import de.hoennig.gittally.config.ConfigLoader
|
||||
import de.hoennig.werkator.build.ArtifactKeys
|
||||
import de.hoennig.werkator.build.ArtifactStore
|
||||
import de.hoennig.werkator.build.BuildResult
|
||||
import de.hoennig.werkator.config.BranchConfig
|
||||
import de.hoennig.werkator.config.ConfigLoader
|
||||
import org.slf4j.LoggerFactory
|
||||
import java.io.IOException
|
||||
import java.nio.file.FileVisitResult
|
||||
@@ -22,7 +22,7 @@ import kotlin.concurrent.write
|
||||
/**
|
||||
* Stores build artifacts on the filesystem under `<root>/branches/<artifactKey>/`.
|
||||
* The root is `artifacts.rootDir` from the config, or the platform default
|
||||
* `XDG_STATE_HOME` (falling back to `~/.local/state`) plus `/gittally/artifacts/<repo-key>` when unset —
|
||||
* `XDG_STATE_HOME` (falling back to `~/.local/state`) plus `/werkator/artifacts/<repo-key>` when unset —
|
||||
* deliberately not `/tmp` like legacy, where artifacts vanished on reboot.
|
||||
*
|
||||
* Each build is assembled in a temporary directory next to its target and moved
|
||||
@@ -115,7 +115,7 @@ class FileArtifactStore(
|
||||
env("XDG_STATE_HOME")?.takeIf { it.isNotBlank() }?.let { Paths.get(it) }
|
||||
?: Paths.get(System.getProperty("user.home"), ".local", "state")
|
||||
return stateHome
|
||||
.resolve("gittally")
|
||||
.resolve("werkator")
|
||||
.resolve("artifacts")
|
||||
.resolve(ArtifactKeys.repoKey(workingDir))
|
||||
.toAbsolutePath()
|
||||
@@ -160,9 +160,9 @@ class FileArtifactStore(
|
||||
}
|
||||
|
||||
/**
|
||||
* The settings [build] ran with, from the build [workspace]'s `.gittally.yml` layered
|
||||
* The settings [build] ran with, from the build [workspace]'s `.werkator.yml` layered
|
||||
* on top of the primary config (see [ConfigLoader.loadForWorktree]) — resolved through
|
||||
* [GitTallyConfig.buildSettings], so a job's own `artifactDirs` are archived and not
|
||||
* [WerkatorConfig.buildSettings], so a job's own `artifactDirs` are archived and not
|
||||
* only the ones its branch would have used.
|
||||
*/
|
||||
private fun buildSettings(
|
||||
+1
-1
@@ -1,4 +1,4 @@
|
||||
package de.hoennig.gittally.build
|
||||
package de.hoennig.werkator.build
|
||||
|
||||
import java.nio.file.Path
|
||||
import java.security.MessageDigest
|
||||
+2
-2
@@ -1,11 +1,11 @@
|
||||
package de.hoennig.gittally.build
|
||||
package de.hoennig.werkator.build
|
||||
|
||||
import java.nio.file.Path
|
||||
|
||||
/**
|
||||
* Persists the artifacts of finished builds (logs plus configured report directories)
|
||||
* and prunes them together with the result retention.
|
||||
* Implemented by `de.hoennig.gittally.artifacts.FileArtifactStore`.
|
||||
* Implemented by `de.hoennig.werkator.artifacts.FileArtifactStore`.
|
||||
*/
|
||||
interface ArtifactStore {
|
||||
/**
|
||||
+4
-4
@@ -1,6 +1,6 @@
|
||||
package de.hoennig.gittally.build
|
||||
package de.hoennig.werkator.build
|
||||
|
||||
import de.hoennig.gittally.git.GitService
|
||||
import de.hoennig.werkator.git.GitService
|
||||
import org.slf4j.LoggerFactory
|
||||
import org.springframework.stereotype.Component
|
||||
import java.nio.file.Files
|
||||
@@ -20,7 +20,7 @@ fun interface BranchWorkspaces {
|
||||
}
|
||||
|
||||
/**
|
||||
* One reusable git worktree per branch under `.git/gittally/worktrees/<branchKey>`,
|
||||
* One reusable git worktree per branch under `.git/werkator/worktrees/<branchKey>`,
|
||||
* checked out detached at the requested commit. Reuse keeps incremental build
|
||||
* caches; the branch's `cleanCommand` decides how much of them survives.
|
||||
*/
|
||||
@@ -50,6 +50,6 @@ class GitWorktreeWorkspaces(
|
||||
}
|
||||
|
||||
companion object {
|
||||
const val WORKTREES_DIR = ".git/gittally/worktrees"
|
||||
const val WORKTREES_DIR = ".git/werkator/worktrees"
|
||||
}
|
||||
}
|
||||
+3
-3
@@ -1,4 +1,4 @@
|
||||
package de.hoennig.gittally.build
|
||||
package de.hoennig.werkator.build
|
||||
|
||||
import org.springframework.context.annotation.Bean
|
||||
import org.springframework.context.annotation.Configuration
|
||||
@@ -8,9 +8,9 @@ import java.nio.file.Paths
|
||||
class BuildConfiguration {
|
||||
/**
|
||||
* Results file relative to the working directory, matching how `ConfigLoader`
|
||||
* resolves the `.git/gittally/` override file. Nothing is touched until the
|
||||
* resolves the `.git/werkator/` override file. Nothing is touched until the
|
||||
* first build runs, so the bean is safe outside a git repository.
|
||||
*/
|
||||
@Bean
|
||||
fun buildResultRepository(): BuildResultRepository = FileBuildResultRepository(Paths.get(".git/gittally/build-results.json"))
|
||||
fun buildResultRepository(): BuildResultRepository = FileBuildResultRepository(Paths.get(".git/werkator/build-results.json"))
|
||||
}
|
||||
+9
-9
@@ -1,9 +1,9 @@
|
||||
package de.hoennig.gittally.build
|
||||
package de.hoennig.werkator.build
|
||||
|
||||
import de.hoennig.gittally.config.BranchConfig
|
||||
import de.hoennig.gittally.config.BuildDefinition
|
||||
import de.hoennig.gittally.config.ConfigLoader
|
||||
import de.hoennig.gittally.gitea.GiteaClient
|
||||
import de.hoennig.werkator.config.BranchConfig
|
||||
import de.hoennig.werkator.config.BuildDefinition
|
||||
import de.hoennig.werkator.config.ConfigLoader
|
||||
import de.hoennig.werkator.gitea.GiteaClient
|
||||
import org.slf4j.LoggerFactory
|
||||
import org.springframework.context.ApplicationEventPublisher
|
||||
import org.springframework.context.event.ContextClosedEvent
|
||||
@@ -93,7 +93,7 @@ class BuildExecutor(
|
||||
return duplicate.runningBuild
|
||||
}
|
||||
val startedAt = Instant.now()
|
||||
val stagingDir = Files.createTempDirectory("gittally-build-")
|
||||
val stagingDir = Files.createTempDirectory("werkator-build-")
|
||||
val runningBuild =
|
||||
RunningBuild(
|
||||
branch = branch,
|
||||
@@ -249,7 +249,7 @@ class BuildExecutor(
|
||||
|
||||
private fun serialWorker(branch: String): ExecutorService =
|
||||
Executors.newSingleThreadExecutor { runnable ->
|
||||
Thread(runnable, "gittally-build-${ArtifactKeys.branchKey(branch)}").apply { isDaemon = true }
|
||||
Thread(runnable, "werkator-build-${ArtifactKeys.branchKey(branch)}").apply { isDaemon = true }
|
||||
}
|
||||
|
||||
private fun runBuildCommands(
|
||||
@@ -324,7 +324,7 @@ class BuildExecutor(
|
||||
input: InputStream,
|
||||
vararg sinks: OutputStream,
|
||||
): Thread =
|
||||
thread(isDaemon = true, name = "gittally-build-log") {
|
||||
thread(isDaemon = true, name = "werkator-build-log") {
|
||||
val buffer = ByteArray(8192)
|
||||
try {
|
||||
while (true) {
|
||||
@@ -480,7 +480,7 @@ class BuildExecutor(
|
||||
|
||||
/**
|
||||
* The effective settings of this run: the branch config with the build [worktree]'s
|
||||
* `.gittally.yml` layered on top (see [ConfigLoader.loadForWorktree]), then the
|
||||
* `.werkator.yml` layered on top (see [ConfigLoader.loadForWorktree]), then the
|
||||
* build definition's overrides applied last — the job wins, and it always comes
|
||||
* from the primary config (`builds` is a pinned section). An unknown build name
|
||||
* (a stale result whose job was removed) falls back to the plain branch settings.
|
||||
+2
-2
@@ -1,6 +1,6 @@
|
||||
package de.hoennig.gittally.build
|
||||
package de.hoennig.werkator.build
|
||||
|
||||
import de.hoennig.gittally.config.BuildDefinition
|
||||
import de.hoennig.werkator.config.BuildDefinition
|
||||
import java.time.Duration
|
||||
import java.time.Instant
|
||||
|
||||
+1
-1
@@ -1,4 +1,4 @@
|
||||
package de.hoennig.gittally.build
|
||||
package de.hoennig.werkator.build
|
||||
|
||||
import java.time.Instant
|
||||
|
||||
+2
-2
@@ -1,6 +1,6 @@
|
||||
package de.hoennig.gittally.build
|
||||
package de.hoennig.werkator.build
|
||||
|
||||
import de.hoennig.gittally.config.BranchConfig
|
||||
import de.hoennig.werkator.config.BranchConfig
|
||||
import org.springframework.context.annotation.Primary
|
||||
import org.springframework.stereotype.Component
|
||||
import java.nio.file.Path
|
||||
+1
-1
@@ -1,4 +1,4 @@
|
||||
package de.hoennig.gittally.build
|
||||
package de.hoennig.werkator.build
|
||||
|
||||
enum class BuildStatus {
|
||||
PENDING,
|
||||
+23
-23
@@ -1,8 +1,8 @@
|
||||
package de.hoennig.gittally.build
|
||||
package de.hoennig.werkator.build
|
||||
|
||||
import de.hoennig.gittally.config.BranchConfig
|
||||
import de.hoennig.gittally.config.DockerConfig
|
||||
import de.hoennig.gittally.git.GitCommandRunner
|
||||
import de.hoennig.werkator.config.BranchConfig
|
||||
import de.hoennig.werkator.config.DockerConfig
|
||||
import de.hoennig.werkator.git.GitCommandRunner
|
||||
import org.slf4j.LoggerFactory
|
||||
import org.springframework.stereotype.Component
|
||||
import java.nio.file.Files
|
||||
@@ -23,7 +23,7 @@ import java.nio.file.Path
|
||||
* same container run; under a rootless daemon the container runs as root, which
|
||||
* already is the host user, so the repair chown degenerates to `0:0`.
|
||||
* Git works inside the container: the primary `.git` is mounted read-only with
|
||||
* `.git/gittally/` masked, see [gitMetadataMounts].
|
||||
* `.git/werkator/` masked, see [gitMetadataMounts].
|
||||
*/
|
||||
@Component
|
||||
class DockerBuildRunner(
|
||||
@@ -114,11 +114,11 @@ class DockerBuildRunner(
|
||||
"docker",
|
||||
"build",
|
||||
"--label",
|
||||
"org.gittally.dockerfile=${docker.dockerfile}",
|
||||
"org.werkator.dockerfile=${docker.dockerfile}",
|
||||
"--label",
|
||||
"org.gittally.dockerfile-sha256=$dockerfileHash",
|
||||
"org.werkator.dockerfile-sha256=$dockerfileHash",
|
||||
"--label",
|
||||
"org.gittally.build-context=${docker.context}",
|
||||
"org.werkator.build-context=${docker.context}",
|
||||
"--label",
|
||||
"${DockerImageInputs.INPUTS_LABEL}=$inputsHash",
|
||||
"-t",
|
||||
@@ -194,11 +194,11 @@ class DockerBuildRunner(
|
||||
"ps",
|
||||
"-aq",
|
||||
"--filter",
|
||||
"label=$GITTALLY_LABEL=true",
|
||||
"label=$WERKATOR_LABEL=true",
|
||||
"--filter",
|
||||
"label=$GITTALLY_LABEL.repository=$repoKey",
|
||||
"label=$WERKATOR_LABEL.repository=$repoKey",
|
||||
"--filter",
|
||||
"label=$GITTALLY_LABEL.role=build",
|
||||
"label=$WERKATOR_LABEL.role=build",
|
||||
),
|
||||
repoDir,
|
||||
)
|
||||
@@ -238,11 +238,11 @@ class DockerBuildRunner(
|
||||
args +=
|
||||
listOf(
|
||||
"--label",
|
||||
"$GITTALLY_LABEL=true",
|
||||
"$WERKATOR_LABEL=true",
|
||||
"--label",
|
||||
"$GITTALLY_LABEL.repository=$repoKey",
|
||||
"$WERKATOR_LABEL.repository=$repoKey",
|
||||
"--label",
|
||||
"$GITTALLY_LABEL.role=build",
|
||||
"$WERKATOR_LABEL.role=build",
|
||||
)
|
||||
args += listOf("--workdir", "$workspace", "--volume", "$workspace:$workspace")
|
||||
args += gitMetadataMounts(workspace, repoDir)
|
||||
@@ -279,12 +279,12 @@ class DockerBuildRunner(
|
||||
}
|
||||
|
||||
/**
|
||||
* Makes git work inside the build container without exposing GitTally's secrets.
|
||||
* Makes git work inside the build container without exposing Werkator's secrets.
|
||||
*
|
||||
* The workspace is a git worktree whose `.git` file points into the primary
|
||||
* repository's `.git`, which is not part of the workspace mount — so any git call
|
||||
* in the build would fail. Three layered mounts fix that (Docker nests mounts by
|
||||
* target path): the primary `.git` read-only, an empty tmpfs masking `.git/gittally/`
|
||||
* target path): the primary `.git` read-only, an empty tmpfs masking `.git/werkator/`
|
||||
* (machine config with `git.token`, control token, build state — the workspace bind
|
||||
* resurfaces only this build's own worktree inside it), and this worktree's admin
|
||||
* directory read-write, so index-refreshing commands like `git status` keep working.
|
||||
@@ -312,9 +312,9 @@ class DockerBuildRunner(
|
||||
return emptyList()
|
||||
}
|
||||
val args = mutableListOf("--volume", "$gitDir:$gitDir:ro")
|
||||
val gittallyDir = gitDir.resolve("gittally")
|
||||
if (Files.isDirectory(gittallyDir)) {
|
||||
args += listOf("--tmpfs", "$gittallyDir")
|
||||
val werkatorDir = gitDir.resolve("werkator")
|
||||
if (Files.isDirectory(werkatorDir)) {
|
||||
args += listOf("--tmpfs", "$werkatorDir")
|
||||
}
|
||||
args += listOf("--volume", "$adminDir:$adminDir")
|
||||
return args
|
||||
@@ -326,15 +326,15 @@ class DockerBuildRunner(
|
||||
): String = commandRunner.runOrThrow(listOf("id", flag), repoDir).stdout.trim()
|
||||
|
||||
companion object {
|
||||
/** Container label namespace; legacy used `org.hostsharing.gittally`. */
|
||||
const val GITTALLY_LABEL = "org.hoennig.gittally"
|
||||
/** Container label namespace; legacy used `org.hostsharing.werkator`. */
|
||||
const val WERKATOR_LABEL = "org.hoennig.werkator"
|
||||
|
||||
fun gradleVolumeName(repoKey: String): String = "gittally-gradle-$repoKey"
|
||||
fun gradleVolumeName(repoKey: String): String = "werkator-gradle-$repoKey"
|
||||
|
||||
fun containerName(
|
||||
repoKey: String,
|
||||
branch: String?,
|
||||
): String = "gittally-build-$repoKey" + (branch?.let { "-${ArtifactKeys.branchKey(it)}" } ?: "")
|
||||
): String = "werkator-build-$repoKey" + (branch?.let { "-${ArtifactKeys.branchKey(it)}" } ?: "")
|
||||
|
||||
private val INSPECT_INPUTS_LABEL_FORMAT = """{{ index .Config.Labels "${DockerImageInputs.INPUTS_LABEL}" }}"""
|
||||
|
||||
+2
-2
@@ -1,4 +1,4 @@
|
||||
package de.hoennig.gittally.build
|
||||
package de.hoennig.werkator.build
|
||||
|
||||
import java.nio.file.Files
|
||||
import java.nio.file.Path
|
||||
@@ -10,7 +10,7 @@ import java.security.MessageDigest
|
||||
* with the configured Dockerfile and context paths, stored as an image label.
|
||||
*/
|
||||
object DockerImageInputs {
|
||||
const val INPUTS_LABEL = "org.gittally.build-inputs-sha256"
|
||||
const val INPUTS_LABEL = "org.werkator.build-inputs-sha256"
|
||||
|
||||
fun dockerfileSha256(dockerfile: Path): String = sha256Hex(Files.readAllBytes(dockerfile))
|
||||
|
||||
+1
-1
@@ -1,4 +1,4 @@
|
||||
package de.hoennig.gittally.build
|
||||
package de.hoennig.werkator.build
|
||||
|
||||
import org.springframework.stereotype.Component
|
||||
import java.nio.file.Files
|
||||
+2
-2
@@ -1,4 +1,4 @@
|
||||
package de.hoennig.gittally.build
|
||||
package de.hoennig.werkator.build
|
||||
|
||||
import com.fasterxml.jackson.databind.DeserializationFeature
|
||||
import com.fasterxml.jackson.databind.ObjectMapper
|
||||
@@ -13,7 +13,7 @@ import java.nio.file.StandardCopyOption
|
||||
import java.time.Instant
|
||||
|
||||
/**
|
||||
* Stores build results as a JSON file, e.g. `.git/gittally/build-results.json`.
|
||||
* Stores build results as a JSON file, e.g. `.git/werkator/build-results.json`.
|
||||
* Writes are atomic (temp file + atomic move) so readers never see partial content.
|
||||
*/
|
||||
class FileBuildResultRepository(
|
||||
+2
-2
@@ -1,6 +1,6 @@
|
||||
package de.hoennig.gittally.build
|
||||
package de.hoennig.werkator.build
|
||||
|
||||
import de.hoennig.gittally.config.BuildDefinition
|
||||
import de.hoennig.werkator.config.BuildDefinition
|
||||
import java.nio.file.Path
|
||||
import java.time.Instant
|
||||
|
||||
+1
-1
@@ -1,4 +1,4 @@
|
||||
package de.hoennig.gittally.commands
|
||||
package de.hoennig.werkator.commands
|
||||
|
||||
/**
|
||||
* Port of the legacy `resolve_branch_name` partial-name matching: a branch-name
|
||||
+3
-3
@@ -1,7 +1,7 @@
|
||||
package de.hoennig.gittally.commands
|
||||
package de.hoennig.werkator.commands
|
||||
|
||||
import de.hoennig.gittally.build.BuildStatus
|
||||
import de.hoennig.gittally.git.GitService
|
||||
import de.hoennig.werkator.build.BuildStatus
|
||||
import de.hoennig.werkator.git.GitService
|
||||
import org.springframework.stereotype.Component
|
||||
import picocli.CommandLine.Command
|
||||
import picocli.CommandLine.ExitCode
|
||||
+2
-2
@@ -1,6 +1,6 @@
|
||||
package de.hoennig.gittally.commands
|
||||
package de.hoennig.werkator.commands
|
||||
|
||||
import de.hoennig.gittally.config.ConfigLoader
|
||||
import de.hoennig.werkator.config.ConfigLoader
|
||||
import org.springframework.stereotype.Component
|
||||
import picocli.CommandLine.Command
|
||||
import picocli.CommandLine.Option
|
||||
+9
-9
@@ -1,13 +1,13 @@
|
||||
package de.hoennig.gittally.commands
|
||||
package de.hoennig.werkator.commands
|
||||
|
||||
import de.hoennig.gittally.build.ArtifactStore
|
||||
import de.hoennig.gittally.build.BuildExecutor
|
||||
import de.hoennig.gittally.build.BuildResult
|
||||
import de.hoennig.gittally.build.BuildResultRepository
|
||||
import de.hoennig.gittally.build.BuildStatus
|
||||
import de.hoennig.gittally.build.RunningBuild
|
||||
import de.hoennig.gittally.config.BuildDefinition
|
||||
import de.hoennig.gittally.server.UiFormats
|
||||
import de.hoennig.werkator.build.ArtifactStore
|
||||
import de.hoennig.werkator.build.BuildExecutor
|
||||
import de.hoennig.werkator.build.BuildResult
|
||||
import de.hoennig.werkator.build.BuildResultRepository
|
||||
import de.hoennig.werkator.build.BuildStatus
|
||||
import de.hoennig.werkator.build.RunningBuild
|
||||
import de.hoennig.werkator.config.BuildDefinition
|
||||
import de.hoennig.werkator.server.UiFormats
|
||||
import org.springframework.stereotype.Component
|
||||
import java.io.IOException
|
||||
import java.nio.channels.Channels
|
||||
+36
-30
@@ -1,7 +1,8 @@
|
||||
package de.hoennig.gittally.commands
|
||||
package de.hoennig.werkator.commands
|
||||
|
||||
import de.hoennig.gittally.SecretFiles
|
||||
import de.hoennig.gittally.git.GitService
|
||||
import de.hoennig.werkator.SecretFiles
|
||||
import de.hoennig.werkator.config.ConfigFiles
|
||||
import de.hoennig.werkator.git.GitService
|
||||
import org.springframework.beans.factory.ObjectProvider
|
||||
import org.springframework.boot.info.BuildProperties
|
||||
import org.springframework.stereotype.Component
|
||||
@@ -13,19 +14,19 @@ import java.nio.file.Paths
|
||||
@Component
|
||||
@Command(
|
||||
name = "init",
|
||||
description = ["Initialize GitTally for the current repository"],
|
||||
description = ["Initialize Werkator for the current repository"],
|
||||
mixinStandardHelpOptions = true,
|
||||
)
|
||||
class InitCommand(
|
||||
private val gitService: GitService,
|
||||
/** The version written into the generated config as `gitTally.version.since`. */
|
||||
/** The version written into the generated config as `werkator.version.since`. */
|
||||
private val buildProperties: ObjectProvider<BuildProperties>? = null,
|
||||
) : Runnable {
|
||||
var workingDir: Path = Paths.get(".")
|
||||
|
||||
@Option(
|
||||
names = ["--systemd"],
|
||||
description = ["also generate a systemd user unit that runs `gittally server` for this repository"],
|
||||
description = ["also generate a systemd user unit that runs `werkator server` for this repository"],
|
||||
)
|
||||
var systemd: Boolean = false
|
||||
|
||||
@@ -56,7 +57,7 @@ class InitCommand(
|
||||
}
|
||||
|
||||
/**
|
||||
* The running version for `gitTally.version.since`; outside a built jar (IDE, tests)
|
||||
* The running version for `werkator.version.since`; outside a built jar (IDE, tests)
|
||||
* there is none, and `0.0.0` then declares no floor at all rather than a wrong one.
|
||||
*/
|
||||
private fun runningVersion(): String = buildProperties?.getIfAvailable()?.version ?: "0.0.0"
|
||||
@@ -99,7 +100,8 @@ class InitCommand(
|
||||
detected: DetectedValues,
|
||||
normalizedWorkingDir: Path,
|
||||
) {
|
||||
val file = root.resolve(".git/gittally/.gittally.yml")
|
||||
val existing = ConfigFiles.firstExisting(root, ConfigFiles.repoInstall)
|
||||
val file = root.resolve(existing)
|
||||
if (file.toFile().exists()) {
|
||||
println("${file.toFile().relativeTo(normalizedWorkingDir.toFile())} already exists — not overwritten")
|
||||
return
|
||||
@@ -107,7 +109,7 @@ class InitCommand(
|
||||
SecretFiles.createDirectoriesOwnerOnly(file.parent)
|
||||
val content =
|
||||
"""
|
||||
# Machine- or user-specific overrides and secrets. Keys here win over .gittally.yml.
|
||||
# Machine- or user-specific overrides and secrets. Keys here win over .werkator.yml.
|
||||
git:
|
||||
account: "${detected.account}" # technical username for git HTTPS authentication
|
||||
token: "" # Gitea API token — never commit this
|
||||
@@ -123,31 +125,35 @@ class InitCommand(
|
||||
detected: DetectedValues,
|
||||
normalizedWorkingDir: Path,
|
||||
) {
|
||||
val file = root.resolve(".gittally.yml")
|
||||
// under either name: writing a second one beside a config under the previous
|
||||
// name would shadow it, and a repository would silently start building
|
||||
// something else than what it says it builds
|
||||
val existing = ConfigFiles.firstExisting(root)
|
||||
val file = root.resolve(existing)
|
||||
if (file.toFile().exists()) {
|
||||
println("${file.toFile().relativeTo(normalizedWorkingDir.toFile())} already exists — not overwritten")
|
||||
return
|
||||
}
|
||||
val content =
|
||||
"""
|
||||
# The GitTally this file is written for.
|
||||
# since: enforced — an older GitTally refuses to read this file instead of
|
||||
# The Werkator this file is written for.
|
||||
# since: enforced — an older Werkator refuses to read this file instead of
|
||||
# silently ignoring the keys it does not know yet.
|
||||
# below: your release marker for a coming major; GitTally decides how strictly
|
||||
# below: your release marker for a coming major; Werkator decides how strictly
|
||||
# to take it, and warns rather than blocks unless the format really broke.
|
||||
gitTally:
|
||||
werkator:
|
||||
version:
|
||||
since: "${runningVersion()}"
|
||||
# below: "2.0"
|
||||
|
||||
server:
|
||||
# Public base URL of this GitTally installation — used for all links posted to Gitea.
|
||||
# Public base URL of this Werkator installation — used for all links posted to Gitea.
|
||||
publicBaseUrl: ""
|
||||
# HTTP port of the `server` subcommand
|
||||
port: 18080
|
||||
# bind address of the `server` subcommand; loopback only, because the UI and the
|
||||
# API are unauthenticated — use 0.0.0.0 only without a reverse proxy in front
|
||||
# (and with the managed nginx below, which reaches GitTally from its container)
|
||||
# (and with the managed nginx below, which reaches Werkator from its container)
|
||||
bindAddress: 127.0.0.1
|
||||
# optional Impressum (legal disclosure) link in the web UI footer; empty hides the link
|
||||
impressumUrl: ""
|
||||
@@ -159,8 +165,8 @@ class InitCommand(
|
||||
httpPort: 8080 # host port published as nginx port 80
|
||||
httpsPort: 8443 # host port published as nginx port 443
|
||||
upstreamHost: "" # host nginx proxies to; empty = serverName
|
||||
containerName: "" # empty = gittally-nginx-<repo-name>
|
||||
stateDir: "" # empty = XDG_STATE_HOME (or ~/.local/state) + /gittally/nginx/<repo-key>
|
||||
containerName: "" # empty = werkator-nginx-<repo-name>
|
||||
stateDir: "" # empty = XDG_STATE_HOME (or ~/.local/state) + /werkator/nginx/<repo-key>
|
||||
letsencryptEmail: "" # e-mail for the Let's Encrypt account; empty registers without one
|
||||
|
||||
# Gitea integration for fetching commits and posting build statuses.
|
||||
@@ -168,7 +174,7 @@ class InitCommand(
|
||||
baseUrl: ${detected.baseUrl} # base URL of the Gitea instance
|
||||
owner: ${detected.owner} # repository owner (user or organisation) for Gitea API (e.g. status checks)
|
||||
repo: ${detected.repo} # repository name
|
||||
statusContext: GitTally # label shown on Gitea commit status checks (default: GitTally)
|
||||
statusContext: werkator # label shown on Gitea commit status checks (default: werkator)
|
||||
|
||||
# Build execution settings, enforced for all builds regardless of their trigger.
|
||||
executor:
|
||||
@@ -178,7 +184,7 @@ class InitCommand(
|
||||
# Named build definitions (jobs); every key names a build.
|
||||
# "default" is the base every other definition inherits its settings from — never
|
||||
# its trigger — and is itself the build of every branch as long as it has one.
|
||||
# A branch may add or override definitions in its own committed .gittally.yml;
|
||||
# A branch may add or override definitions in its own committed .werkator.yml;
|
||||
# they apply to that branch alone, so a new job can be tried out on one branch.
|
||||
builds:
|
||||
default:
|
||||
@@ -218,11 +224,11 @@ class InitCommand(
|
||||
# atTimes: ["01:00"]
|
||||
# branches: ["master"]
|
||||
# buildCommand: ./gradlew pitestFull
|
||||
# statusContext: GitTally/pitest
|
||||
# statusContext: werkator/pitest
|
||||
|
||||
# Build artifact storage and retention.
|
||||
artifacts:
|
||||
# root directory for stored artifacts; empty = XDG_STATE_HOME (or ~/.local/state) + /gittally/artifacts/<repo-key>
|
||||
# root directory for stored artifacts; empty = XDG_STATE_HOME (or ~/.local/state) + /werkator/artifacts/<repo-key>
|
||||
rootDir: ""
|
||||
# number of builds to keep per branch
|
||||
retentionPerBranch: 3
|
||||
@@ -256,14 +262,14 @@ class InitCommand(
|
||||
) {
|
||||
val jarPath = jarPathResolver()
|
||||
if (jarPath == null) {
|
||||
println("Error: cannot determine the GitTally jar path — run `init --systemd` via `java -jar <path-to>/gittally.jar`")
|
||||
println("Error: cannot determine the Werkator jar path — run `init --systemd` via `java -jar <path-to>/werkator.jar`")
|
||||
return
|
||||
}
|
||||
val gittallyDir = root.resolve(".git/gittally")
|
||||
SecretFiles.createDirectoriesOwnerOnly(gittallyDir)
|
||||
val werkatorDir = root.resolve(".git/werkator")
|
||||
SecretFiles.createDirectoriesOwnerOnly(werkatorDir)
|
||||
val unitName = SystemdServiceFiles.unitName(root)
|
||||
val unitFile = gittallyDir.resolve(unitName)
|
||||
val envFile = gittallyDir.resolve(SystemdServiceFiles.ENV_FILE_NAME)
|
||||
val unitFile = werkatorDir.resolve(unitName)
|
||||
val envFile = werkatorDir.resolve(SystemdServiceFiles.ENV_FILE_NAME)
|
||||
|
||||
unitFile.toFile().writeText(
|
||||
SystemdServiceFiles.unitFileContent(
|
||||
@@ -283,9 +289,9 @@ class InitCommand(
|
||||
}
|
||||
|
||||
// the nightly Docker cleanup is host-global: every repository generates the same
|
||||
// units, so with several GitTally instances the symlinks simply coincide
|
||||
val pruneServiceFile = gittallyDir.resolve(SystemdServiceFiles.PRUNE_SERVICE_NAME)
|
||||
val pruneTimerFile = gittallyDir.resolve(SystemdServiceFiles.PRUNE_TIMER_NAME)
|
||||
// units, so with several Werkator instances the symlinks simply coincide
|
||||
val pruneServiceFile = werkatorDir.resolve(SystemdServiceFiles.PRUNE_SERVICE_NAME)
|
||||
val pruneTimerFile = werkatorDir.resolve(SystemdServiceFiles.PRUNE_TIMER_NAME)
|
||||
pruneServiceFile.toFile().writeText(SystemdServiceFiles.pruneServiceContent())
|
||||
println("created ${pruneServiceFile.toFile().relativeTo(normalizedWorkingDir.toFile())}")
|
||||
pruneTimerFile.toFile().writeText(SystemdServiceFiles.pruneTimerContent())
|
||||
+5
-5
@@ -1,9 +1,9 @@
|
||||
package de.hoennig.gittally.commands
|
||||
package de.hoennig.werkator.commands
|
||||
|
||||
import de.hoennig.gittally.build.BuildResult
|
||||
import de.hoennig.gittally.build.BuildResultRepository
|
||||
import de.hoennig.gittally.build.BuildStatus
|
||||
import de.hoennig.gittally.git.GitService
|
||||
import de.hoennig.werkator.build.BuildResult
|
||||
import de.hoennig.werkator.build.BuildResultRepository
|
||||
import de.hoennig.werkator.build.BuildStatus
|
||||
import de.hoennig.werkator.git.GitService
|
||||
import org.springframework.stereotype.Component
|
||||
import picocli.CommandLine.Command
|
||||
import picocli.CommandLine.ExitCode
|
||||
+6
-6
@@ -1,7 +1,7 @@
|
||||
package de.hoennig.gittally.commands
|
||||
package de.hoennig.werkator.commands
|
||||
|
||||
import de.hoennig.gittally.GitTallyApplication
|
||||
import de.hoennig.gittally.config.ConfigLoader
|
||||
import de.hoennig.werkator.WerkatorApplication
|
||||
import de.hoennig.werkator.config.ConfigLoader
|
||||
import org.springframework.boot.WebApplicationType
|
||||
import org.springframework.boot.builder.SpringApplicationBuilder
|
||||
import org.springframework.context.ApplicationListener
|
||||
@@ -24,7 +24,7 @@ import java.util.concurrent.CountDownLatch
|
||||
@Component
|
||||
@Command(
|
||||
name = "server",
|
||||
description = ["Start the GitTally server"],
|
||||
description = ["Start the Werkator server"],
|
||||
mixinStandardHelpOptions = true,
|
||||
)
|
||||
class ServerCommand(
|
||||
@@ -35,7 +35,7 @@ class ServerCommand(
|
||||
override fun run() {
|
||||
val config = configLoader.load(workingDir)
|
||||
val context =
|
||||
SpringApplicationBuilder(GitTallyApplication::class.java)
|
||||
SpringApplicationBuilder(WerkatorApplication::class.java)
|
||||
.web(WebApplicationType.SERVLET)
|
||||
.profiles(SERVER_PROFILE)
|
||||
.properties(
|
||||
@@ -43,7 +43,7 @@ class ServerCommand(
|
||||
"server.address=${config.server.bindAddress}",
|
||||
).run()
|
||||
val port = context.environment.getProperty("local.server.port", config.server.port.toString())
|
||||
println("GitTally server listening on http://${config.server.bindAddress}:$port/ — Ctrl-C to stop")
|
||||
println("Werkator server listening on http://${config.server.bindAddress}:$port/ — Ctrl-C to stop")
|
||||
awaitShutdown(context)
|
||||
}
|
||||
|
||||
+4
-4
@@ -1,8 +1,8 @@
|
||||
package de.hoennig.gittally.commands
|
||||
package de.hoennig.werkator.commands
|
||||
|
||||
import de.hoennig.gittally.build.BuildResult
|
||||
import de.hoennig.gittally.build.BuildResultRepository
|
||||
import de.hoennig.gittally.server.UiFormats
|
||||
import de.hoennig.werkator.build.BuildResult
|
||||
import de.hoennig.werkator.build.BuildResultRepository
|
||||
import de.hoennig.werkator.server.UiFormats
|
||||
import org.springframework.stereotype.Component
|
||||
import picocli.CommandLine.Command
|
||||
import picocli.CommandLine.ExitCode
|
||||
+13
-13
@@ -1,21 +1,21 @@
|
||||
package de.hoennig.gittally.commands
|
||||
package de.hoennig.werkator.commands
|
||||
|
||||
import java.nio.file.Path
|
||||
|
||||
/**
|
||||
* Generates the content of the systemd user unit and its `EnvironmentFile` for running
|
||||
* `gittally server` as a service — the shape of the legacy `generate_systemd_config`,
|
||||
* `werkator server` as a service — the shape of the legacy `generate_systemd_config`,
|
||||
* without the self-copy/self-update machinery (the unit points at the jar in place).
|
||||
*/
|
||||
object SystemdServiceFiles {
|
||||
const val ENV_FILE_NAME = "gittally.env"
|
||||
const val ENV_FILE_NAME = "werkator.env"
|
||||
|
||||
/** Host-global unit names of the nightly Docker cleanup — shared by all GitTally repositories on the host. */
|
||||
const val PRUNE_SERVICE_NAME = "gittally-docker-prune.service"
|
||||
const val PRUNE_TIMER_NAME = "gittally-docker-prune.timer"
|
||||
/** Host-global unit names of the nightly Docker cleanup — shared by all Werkator repositories on the host. */
|
||||
const val PRUNE_SERVICE_NAME = "werkator-docker-prune.service"
|
||||
const val PRUNE_TIMER_NAME = "werkator-docker-prune.timer"
|
||||
|
||||
/** Per-repository unit name, because one GitTally instance serves exactly one repository. */
|
||||
fun unitName(repoRoot: Path): String = "gittally-${sanitize(repoRoot.fileName.toString())}.service"
|
||||
/** Per-repository unit name, because one Werkator instance serves exactly one repository. */
|
||||
fun unitName(repoRoot: Path): String = "werkator-${sanitize(repoRoot.fileName.toString())}.service"
|
||||
|
||||
fun unitFileContent(
|
||||
repoRoot: Path,
|
||||
@@ -25,7 +25,7 @@ object SystemdServiceFiles {
|
||||
): String =
|
||||
"""
|
||||
[Unit]
|
||||
Description=GitTally CI for ${repoRoot.fileName}
|
||||
Description=Werkator CI for ${repoRoot.fileName}
|
||||
Wants=network-online.target
|
||||
After=network-online.target docker.service
|
||||
|
||||
@@ -49,7 +49,7 @@ object SystemdServiceFiles {
|
||||
fun pruneServiceContent(): String =
|
||||
"""
|
||||
[Unit]
|
||||
Description=Clean up unused Docker containers and images (GitTally)
|
||||
Description=Clean up unused Docker containers and images (Werkator)
|
||||
|
||||
[Service]
|
||||
Type=oneshot
|
||||
@@ -62,7 +62,7 @@ object SystemdServiceFiles {
|
||||
fun pruneTimerContent(): String =
|
||||
"""
|
||||
[Unit]
|
||||
Description=Nightly Docker cleanup before the auto builds (GitTally)
|
||||
Description=Nightly Docker cleanup before the auto builds (Werkator)
|
||||
|
||||
[Timer]
|
||||
OnCalendar=*-*-* 02:00:00
|
||||
@@ -74,8 +74,8 @@ object SystemdServiceFiles {
|
||||
|
||||
fun envFileContent(): String =
|
||||
"""
|
||||
# EnvironmentFile for the GitTally systemd service.
|
||||
# GitTally itself is configured via .gittally.yml and .git/gittally/.gittally.yml,
|
||||
# EnvironmentFile for the Werkator systemd service.
|
||||
# Werkator itself is configured via .werkator.yml and .git/werkator/.werkator.yml,
|
||||
# not via environment variables; this file only tunes the JVM process.
|
||||
#JAVA_OPTS=-Xmx256m
|
||||
""".trimIndent() + "\n"
|
||||
+1
-1
@@ -1,4 +1,4 @@
|
||||
package de.hoennig.gittally.config
|
||||
package de.hoennig.werkator.config
|
||||
|
||||
import java.time.Duration
|
||||
import java.time.Instant
|
||||
@@ -0,0 +1,57 @@
|
||||
package de.hoennig.werkator.config
|
||||
|
||||
import java.nio.file.Files
|
||||
import java.nio.file.Path
|
||||
|
||||
/**
|
||||
* The names a configuration file is looked up under, current name first and the name
|
||||
* from before the rename to Werkator second — spelled exactly as it was.
|
||||
*
|
||||
* The fallback exists because a missing configuration is not an error: it leaves every
|
||||
* setting at its default. An installation that updates without moving its files would
|
||||
* therefore not fail, it would come up as a plausible-looking instance that has
|
||||
* forgotten its credentials, its addresses, and what it builds.
|
||||
*/
|
||||
object ConfigFiles {
|
||||
/** The committed configuration, at the repository root and in a build worktree. */
|
||||
const val COMMITTED = ".werkator.yml"
|
||||
|
||||
/** The machine-specific configuration inside `.git`; secrets live here. */
|
||||
const val REPO_INSTALL = ".git/werkator/$COMMITTED"
|
||||
|
||||
/** The name the committed configuration had before the rename. */
|
||||
const val LEGACY_COMMITTED = ".gittally.yml"
|
||||
|
||||
private const val LEGACY_REPO_INSTALL = ".git/gittally/$LEGACY_COMMITTED"
|
||||
|
||||
/**
|
||||
* The state directory moves without touching the file inside it, so between the
|
||||
* move and the rename the machine configuration sits under the old name in the
|
||||
* new directory. `StateDirMigration` closes that gap where it moves the directory
|
||||
* itself; this candidate covers a directory somebody moved by hand.
|
||||
*/
|
||||
private const val MOVED_REPO_INSTALL = ".git/werkator/$LEGACY_COMMITTED"
|
||||
|
||||
/** Both names of the committed configuration, current first. */
|
||||
val committed = listOf(COMMITTED, LEGACY_COMMITTED)
|
||||
|
||||
/** Every path the machine-specific configuration can sit at, current first. */
|
||||
val repoInstall = listOf(REPO_INSTALL, MOVED_REPO_INSTALL, LEGACY_REPO_INSTALL)
|
||||
|
||||
/**
|
||||
* The first of [candidates] that exists under [dir], or the current name when none
|
||||
* does — so a message about a file names the one to write, never the one that is
|
||||
* history.
|
||||
*/
|
||||
fun firstExisting(
|
||||
dir: Path,
|
||||
candidates: List<String> = committed,
|
||||
): String = candidates.firstOrNull { Files.isRegularFile(dir.resolve(it)) } ?: candidates.first()
|
||||
|
||||
/**
|
||||
* The committed configuration as [read] answers it for a name, current name first.
|
||||
* Null when neither name is committed — used where the file is read out of git
|
||||
* rather than off the filesystem.
|
||||
*/
|
||||
fun readCommitted(read: (String) -> String?): String? = committed.firstNotNullOfOrNull(read)
|
||||
}
|
||||
+28
-25
@@ -1,4 +1,4 @@
|
||||
package de.hoennig.gittally.config
|
||||
package de.hoennig.werkator.config
|
||||
|
||||
import com.fasterxml.jackson.databind.DeserializationFeature
|
||||
import com.fasterxml.jackson.databind.ObjectMapper
|
||||
@@ -17,7 +17,7 @@ import java.util.concurrent.ConcurrentHashMap
|
||||
|
||||
@Service
|
||||
class ConfigLoader(
|
||||
/** The running version, for the `gitTally.version` check; absent outside a built jar (IDE, tests). */
|
||||
/** The running version, for the `werkator.version` check; absent outside a built jar (IDE, tests). */
|
||||
private val buildProperties: ObjectProvider<BuildProperties>? = null,
|
||||
) {
|
||||
private val log = LoggerFactory.getLogger(ConfigLoader::class.java)
|
||||
@@ -37,21 +37,21 @@ class ConfigLoader(
|
||||
/** Section-level warnings already reported, keyed by a fixed slug; the config is loaded on every poll cycle. */
|
||||
private val warnedSections = ConcurrentHashMap.newKeySet<String>()
|
||||
|
||||
fun load(workingDir: Path = Paths.get(".")): GitTallyConfig = toConfig(loadRaw(workingDir))
|
||||
fun load(workingDir: Path = Paths.get(".")): WerkatorConfig = toConfig(loadRaw(workingDir))
|
||||
|
||||
/**
|
||||
* Config for building a branch in [worktreeDir]: the worktree's `.gittally.yml`
|
||||
* Config for building a branch in [worktreeDir]: the worktree's `.werkator.yml`
|
||||
* (the committed config of the branch being built) is applied as the branch layer,
|
||||
* see [loadWithBranchLayer]. With no worktree `.gittally.yml` this is identical
|
||||
* see [loadWithBranchLayer]. With no worktree `.werkator.yml` this is identical
|
||||
* to [load].
|
||||
*/
|
||||
fun loadForWorktree(
|
||||
workingDir: Path,
|
||||
worktreeDir: Path,
|
||||
): GitTallyConfig = withBranchLayer(workingDir, loadFile(worktreeDir.resolve(".gittally.yml").toFile()))
|
||||
): WerkatorConfig = withBranchLayer(workingDir, loadFile(worktreeDir.resolve(ConfigFiles.firstExisting(worktreeDir)).toFile()))
|
||||
|
||||
/**
|
||||
* The primary/`.git` config with the committed `.gittally.yml` of one branch
|
||||
* The primary/`.git` config with the committed `.werkator.yml` of one branch
|
||||
* ([branchConfigYaml], null or blank for a branch without one) merged on top:
|
||||
* precedence branch > `.git` > project. A branch describes its own CI — build
|
||||
* settings (`buildCommand`, `cleanCommand`, `artifactDirs`, `docker.image`/`env`, …)
|
||||
@@ -70,25 +70,25 @@ class ConfigLoader(
|
||||
fun loadWithBranchLayer(
|
||||
workingDir: Path,
|
||||
branchConfigYaml: String?,
|
||||
): GitTallyConfig = withBranchLayer(workingDir, parseYaml(branchConfigYaml))
|
||||
): WerkatorConfig = withBranchLayer(workingDir, parseYaml(branchConfigYaml))
|
||||
|
||||
private fun withBranchLayer(
|
||||
workingDir: Path,
|
||||
branchLayer: Map<String, Any?>,
|
||||
): GitTallyConfig {
|
||||
): WerkatorConfig {
|
||||
// scoped to this branch: an incompatible branch config fails its own builds and
|
||||
// must never stop the server or hold up the branches that are fine
|
||||
checkVersion(branchLayer, "the committed .gittally.yml of this branch", BRANCH_HINT)
|
||||
checkTriggerBlocks(branchLayer, "the committed .gittally.yml of this branch", BRANCH_HINT)
|
||||
checkVersion(branchLayer, "the committed .werkator.yml of this branch", BRANCH_HINT)
|
||||
checkTriggerBlocks(branchLayer, "the committed .werkator.yml of this branch", BRANCH_HINT)
|
||||
return toConfig(deepMerge(loadRaw(workingDir), stripPinned(branchLayer)))
|
||||
}
|
||||
|
||||
private fun toConfig(raw: Map<String, Any?>): GitTallyConfig {
|
||||
private fun toConfig(raw: Map<String, Any?>): WerkatorConfig {
|
||||
val config =
|
||||
if (raw.isEmpty()) {
|
||||
GitTallyConfig()
|
||||
WerkatorConfig()
|
||||
} else {
|
||||
yaml.convertValue(resolveBuildSections(dropNonDefinitionBuilds(raw)), GitTallyConfig::class.java)
|
||||
yaml.convertValue(resolveBuildSections(dropNonDefinitionBuilds(raw)), WerkatorConfig::class.java)
|
||||
}
|
||||
return defaultPublicBaseUrl(config)
|
||||
}
|
||||
@@ -265,7 +265,7 @@ class ConfigLoader(
|
||||
}
|
||||
|
||||
/** Legacy default: an empty `server.publicBaseUrl` becomes `https://<nginx.serverName>/`. */
|
||||
private fun defaultPublicBaseUrl(config: GitTallyConfig): GitTallyConfig {
|
||||
private fun defaultPublicBaseUrl(config: WerkatorConfig): WerkatorConfig {
|
||||
if (config.server.publicBaseUrl.isNotBlank() ||
|
||||
config.server.nginx.serverName
|
||||
.isBlank()
|
||||
@@ -276,18 +276,21 @@ class ConfigLoader(
|
||||
}
|
||||
|
||||
fun loadRaw(workingDir: Path = Paths.get(".")): Map<String, Any?> {
|
||||
val repoInstall = loadFile(workingDir.resolve(".git/gittally/.gittally.yml").toFile())
|
||||
val project = loadFile(workingDir.resolve(".gittally.yml").toFile())
|
||||
// each layer under its current name, or under the one it had before the rename
|
||||
val repoInstallName = ConfigFiles.firstExisting(workingDir, ConfigFiles.repoInstall)
|
||||
val projectName = ConfigFiles.firstExisting(workingDir)
|
||||
val repoInstall = loadFile(workingDir.resolve(repoInstallName).toFile())
|
||||
val project = loadFile(workingDir.resolve(projectName).toFile())
|
||||
// per file, so the message names the file to fix — the merged map has no provenance
|
||||
checkVersion(project, ".gittally.yml", ROLLBACK_HINT)
|
||||
checkVersion(repoInstall, ".git/gittally/.gittally.yml", ROLLBACK_HINT)
|
||||
checkTriggerBlocks(project, ".gittally.yml", ROLLBACK_HINT)
|
||||
checkTriggerBlocks(repoInstall, ".git/gittally/.gittally.yml", ROLLBACK_HINT)
|
||||
checkVersion(project, projectName, ROLLBACK_HINT)
|
||||
checkVersion(repoInstall, repoInstallName, ROLLBACK_HINT)
|
||||
checkTriggerBlocks(project, projectName, ROLLBACK_HINT)
|
||||
checkTriggerBlocks(repoInstall, repoInstallName, ROLLBACK_HINT)
|
||||
return deepMerge(project, repoInstall)
|
||||
}
|
||||
|
||||
/**
|
||||
* Enforces the `gitTally.version` declaration of one configuration file.
|
||||
* Enforces the `werkator.version` declaration of one configuration file.
|
||||
* An incompatible file throws — reading it would mean honoring keys that mean
|
||||
* something else now, which is worse than not building. A file that merely exceeds
|
||||
* its own `below` marker is a warning, logged once: an unmaintained marker must
|
||||
@@ -314,7 +317,7 @@ class ConfigLoader(
|
||||
|
||||
@Suppress("UNCHECKED_CAST")
|
||||
private fun requirementOf(raw: Map<String, Any?>): VersionRequirement {
|
||||
val version = (raw["gitTally"] as? Map<String, Any?>)?.get("version") as? Map<String, Any?> ?: return VersionRequirement()
|
||||
val version = (raw["werkator"] as? Map<String, Any?>)?.get("version") as? Map<String, Any?> ?: return VersionRequirement()
|
||||
return VersionRequirement(
|
||||
since = version["since"]?.toString()?.trim().orEmpty(),
|
||||
below = version["below"]?.toString()?.trim().orEmpty(),
|
||||
@@ -329,7 +332,7 @@ class ConfigLoader(
|
||||
return yaml.readValue(file, Map::class.java) as Map<String, Any?>
|
||||
}
|
||||
|
||||
/** Parses a `.gittally.yml` read from git (not from disk); blank or null yields no layer. */
|
||||
/** Parses a `.werkator.yml` read from git (not from disk); blank or null yields no layer. */
|
||||
private fun parseYaml(text: String?): Map<String, Any?> {
|
||||
if (text.isNullOrBlank()) return emptyMap()
|
||||
@Suppress("UNCHECKED_CAST")
|
||||
@@ -411,7 +414,7 @@ class ConfigLoader(
|
||||
private const val NO_TRIGGER_WARNING = "no-build-triggered"
|
||||
|
||||
private const val ROLLBACK_HINT =
|
||||
"Migrate the file, or roll back to the GitTally version it was written for."
|
||||
"Migrate the file, or roll back to the Werkator version it was written for."
|
||||
|
||||
private const val BRANCH_HINT =
|
||||
"Migrate the file on this branch; the other branches keep building."
|
||||
+20
-20
@@ -1,33 +1,33 @@
|
||||
package de.hoennig.gittally.config
|
||||
package de.hoennig.werkator.config
|
||||
|
||||
/**
|
||||
* The GitTally version a configuration file declares itself for, the `gitTally.version`
|
||||
* The Werkator version a configuration file declares itself for, the `werkator.version`
|
||||
* section:
|
||||
*
|
||||
* ```yaml
|
||||
* gitTally:
|
||||
* werkator:
|
||||
* version:
|
||||
* since: "0.9.16" # always hard: an older GitTally refuses this file
|
||||
* below: "2.0" # GitTally decides how hard, see ConfigVersions.verdict
|
||||
* since: "0.9.16" # always hard: an older Werkator refuses this file
|
||||
* below: "2.0" # Werkator decides how hard, see ConfigVersions.verdict
|
||||
* ```
|
||||
*
|
||||
* There is deliberately no version of the file format itself (no `apiVersion`): no API is
|
||||
* involved — GitTally reads its own configuration — and only one configuration generation
|
||||
* involved — Werkator reads its own configuration — and only one configuration generation
|
||||
* is ever supported. The declared version exists to make an incompatibility nameable,
|
||||
* never to run two parsers.
|
||||
*/
|
||||
data class VersionRequirement(
|
||||
/** Oldest GitTally that understands this file; empty means the file does not say. */
|
||||
/** Oldest Werkator that understands this file; empty means the file does not say. */
|
||||
val since: String = "",
|
||||
/** First GitTally this file was not released for; empty means no ceiling. */
|
||||
/** First Werkator this file was not released for; empty means no ceiling. */
|
||||
val below: String = "",
|
||||
)
|
||||
|
||||
data class GitTallyMeta(
|
||||
data class WerkatorMeta(
|
||||
val version: VersionRequirement = VersionRequirement(),
|
||||
)
|
||||
|
||||
/** What a [VersionRequirement] means for the GitTally that reads the file. */
|
||||
/** What a [VersionRequirement] means for the Werkator that reads the file. */
|
||||
sealed interface VersionVerdict {
|
||||
/** The running version is covered by the declaration. */
|
||||
data object Compatible : VersionVerdict
|
||||
@@ -37,24 +37,24 @@ sealed interface VersionVerdict {
|
||||
val message: String,
|
||||
) : VersionVerdict
|
||||
|
||||
/** Not usable: the file predates a change that GitTally cannot bridge. */
|
||||
/** Not usable: the file predates a change that Werkator cannot bridge. */
|
||||
data class Incompatible(
|
||||
val message: String,
|
||||
) : VersionVerdict
|
||||
}
|
||||
|
||||
/** A configuration file this GitTally must not read; carries the file's name in its message. */
|
||||
/** A configuration file this Werkator must not read; carries the file's name in its message. */
|
||||
open class ConfigException(
|
||||
message: String,
|
||||
) : RuntimeException(message)
|
||||
|
||||
/** The file declares a GitTally that cannot read it, see [ConfigVersions]. */
|
||||
/** The file declares a Werkator that cannot read it, see [ConfigVersions]. */
|
||||
class ConfigVersionException(
|
||||
message: String,
|
||||
) : ConfigException(message)
|
||||
|
||||
/**
|
||||
* The file is written in a shape this GitTally no longer reads. Refusing it is the point:
|
||||
* The file is written in a shape this Werkator no longer reads. Refusing it is the point:
|
||||
* a key that moved and is silently ignored means a build that quietly stops happening.
|
||||
*/
|
||||
class ConfigFormatException(
|
||||
@@ -64,7 +64,7 @@ class ConfigFormatException(
|
||||
object ConfigVersions {
|
||||
/**
|
||||
* The version in which the configuration format last changed incompatibly — a file
|
||||
* written before it cannot be read by this GitTally. Empty while no such change has
|
||||
* written before it cannot be read by this werkator. Empty while no such change has
|
||||
* happened; set it to the release that introduces one, together with the migration
|
||||
* note the message points at.
|
||||
*/
|
||||
@@ -76,13 +76,13 @@ object ConfigVersions {
|
||||
/**
|
||||
* Decides what [requirement] means for [running].
|
||||
*
|
||||
* `since` is always hard — a file that needs a newer GitTally cannot be honored, and
|
||||
* `since` is always hard — a file that needs a newer Werkator cannot be honored, and
|
||||
* silently ignoring its unknown keys is exactly the failure mode this section exists
|
||||
* to prevent.
|
||||
*
|
||||
* `below` alone only warns: it is the team's release marker, and an unmaintained
|
||||
* marker must never stop a CI. Whether the running version really broke the file is
|
||||
* GitTally's own knowledge ([FORMAT_BROKE_IN]) — a file written before that change
|
||||
* Werkator's own knowledge ([FORMAT_BROKE_IN]) — a file written before that change
|
||||
* and read after it is incompatible regardless of what it declares as its ceiling.
|
||||
*/
|
||||
fun verdict(
|
||||
@@ -95,13 +95,13 @@ object ConfigVersions {
|
||||
val since = parse(requirement.since)
|
||||
if (since != null && version < since) {
|
||||
return VersionVerdict.Incompatible(
|
||||
"needs GitTally ${requirement.since} or newer (gitTally.version.since), this is $running",
|
||||
"needs Werkator ${requirement.since} or newer (werkator.version.since), this is $running",
|
||||
)
|
||||
}
|
||||
val broke = parse(brokeIn)
|
||||
if (since != null && broke != null && since < broke && version >= broke) {
|
||||
return VersionVerdict.Incompatible(
|
||||
"is written for GitTally ${requirement.since} (gitTally.version.since), " +
|
||||
"is written for Werkator ${requirement.since} (werkator.version.since), " +
|
||||
"but the configuration format changed incompatibly in $brokeIn" +
|
||||
brokeDescription.takeIf { it.isNotBlank() }?.let { ": $it" }.orEmpty(),
|
||||
)
|
||||
@@ -109,7 +109,7 @@ object ConfigVersions {
|
||||
val below = parse(requirement.below)
|
||||
if (below != null && version >= below) {
|
||||
return VersionVerdict.Warn(
|
||||
"was released for GitTally below ${requirement.below} (gitTally.version.below), this is $running",
|
||||
"was released for Werkator below ${requirement.below} (werkator.version.below), this is $running",
|
||||
)
|
||||
}
|
||||
return VersionVerdict.Compatible
|
||||
+1
-1
@@ -1,4 +1,4 @@
|
||||
package de.hoennig.gittally.config
|
||||
package de.hoennig.werkator.config
|
||||
|
||||
import java.time.Duration
|
||||
|
||||
+10
-10
@@ -1,10 +1,10 @@
|
||||
package de.hoennig.gittally.config
|
||||
package de.hoennig.werkator.config
|
||||
|
||||
import com.fasterxml.jackson.annotation.JsonProperty
|
||||
|
||||
data class GitTallyConfig(
|
||||
/** What this file declares about the GitTally that reads it; see [VersionRequirement]. */
|
||||
val gitTally: GitTallyMeta = GitTallyMeta(),
|
||||
data class WerkatorConfig(
|
||||
/** What this file declares about the Werkator that reads it; see [VersionRequirement]. */
|
||||
val werkator: WerkatorMeta = WerkatorMeta(),
|
||||
val server: ServerConfig = ServerConfig(),
|
||||
val git: GitConfig = GitConfig(),
|
||||
val gitea: GiteaConfig = GiteaConfig(),
|
||||
@@ -61,7 +61,7 @@ data class ServerConfig(
|
||||
)
|
||||
|
||||
/**
|
||||
* Opt-in managed nginx+certbot Docker container serving GitTally over HTTPS,
|
||||
* Opt-in managed nginx+certbot Docker container serving Werkator over HTTPS,
|
||||
* for hosts without a usable reverse proxy (ADR 0005). Off by default; the
|
||||
* reverse-proxy deployment from `docs/deployment.md` stays the recommended setup.
|
||||
*/
|
||||
@@ -76,11 +76,11 @@ data class NginxConfig(
|
||||
val httpsPort: Int = 8443,
|
||||
/** Host nginx proxies to; empty uses [serverName] (the container cannot reach `localhost`). */
|
||||
val upstreamHost: String = "",
|
||||
/** Name of the managed container; empty means `gittally-nginx-<repo-name>`. */
|
||||
/** Name of the managed container; empty means `werkator-nginx-<repo-name>`. */
|
||||
val containerName: String = "",
|
||||
/**
|
||||
* Directory for nginx config, certificates, and logs; empty means the platform
|
||||
* default `XDG_STATE_HOME` (or `~/.local/state`) + `/gittally/nginx/<repo-key>`.
|
||||
* default `XDG_STATE_HOME` (or `~/.local/state`) + `/werkator/nginx/<repo-key>`.
|
||||
*/
|
||||
val stateDir: String = "",
|
||||
/** E-mail for the Let's Encrypt account; empty registers without one. */
|
||||
@@ -96,7 +96,7 @@ data class GiteaConfig(
|
||||
val baseUrl: String = "",
|
||||
val owner: String = "",
|
||||
val repo: String = "",
|
||||
val statusContext: String = "GitTally",
|
||||
val statusContext: String = "werkator",
|
||||
)
|
||||
|
||||
data class ArtifactsConfig(
|
||||
@@ -117,7 +117,7 @@ data class ArtifactsConfig(
|
||||
val keepLatestGreen: Boolean = true,
|
||||
/**
|
||||
* Root directory for stored build artifacts; empty means the platform default
|
||||
* `XDG_STATE_HOME` (or `~/.local/state`) + `/gittally/artifacts/<repo-key>`.
|
||||
* `XDG_STATE_HOME` (or `~/.local/state`) + `/werkator/artifacts/<repo-key>`.
|
||||
*/
|
||||
val rootDir: String = "",
|
||||
)
|
||||
@@ -130,7 +130,7 @@ data class WatcherConfig(
|
||||
* Honor the `branches.<name>.requirePullRequest` gates. Set false for a plain git
|
||||
* origin without pull-request refs (no Gitea/GitHub) — gated branches then build
|
||||
* on new commits like any other branch. Typically overridden per machine in
|
||||
* `.git/gittally/.gittally.yml` when the committed config enables the gates.
|
||||
* `.git/werkator/.werkator.yml` when the committed config enables the gates.
|
||||
*/
|
||||
val pullRequestGate: Boolean = true,
|
||||
/**
|
||||
+6
-6
@@ -1,4 +1,4 @@
|
||||
package de.hoennig.gittally.git
|
||||
package de.hoennig.werkator.git
|
||||
|
||||
import java.nio.file.Files
|
||||
import java.nio.file.attribute.PosixFilePermissions
|
||||
@@ -15,10 +15,10 @@ object GitAskPass {
|
||||
#!/bin/sh
|
||||
case "${'$'}1" in
|
||||
*[Uu]sername*)
|
||||
printf '%s\n' "${'$'}GITTALLY_GIT_ACCOUNT"
|
||||
printf '%s\n' "${'$'}WERKATOR_GIT_ACCOUNT"
|
||||
;;
|
||||
*)
|
||||
printf '%s\n' "${'$'}GITTALLY_GIT_TOKEN"
|
||||
printf '%s\n' "${'$'}WERKATOR_GIT_TOKEN"
|
||||
;;
|
||||
esac
|
||||
""".trimIndent() + "\n"
|
||||
@@ -30,7 +30,7 @@ object GitAskPass {
|
||||
): T {
|
||||
val script =
|
||||
Files.createTempFile(
|
||||
"gittally-askpass",
|
||||
"werkator-askpass",
|
||||
".sh",
|
||||
PosixFilePermissions.asFileAttribute(PosixFilePermissions.fromString("rwx------")),
|
||||
)
|
||||
@@ -40,8 +40,8 @@ object GitAskPass {
|
||||
mapOf(
|
||||
"GIT_ASKPASS" to script.toAbsolutePath().toString(),
|
||||
"GIT_TERMINAL_PROMPT" to "0",
|
||||
"GITTALLY_GIT_ACCOUNT" to account,
|
||||
"GITTALLY_GIT_TOKEN" to token,
|
||||
"WERKATOR_GIT_ACCOUNT" to account,
|
||||
"WERKATOR_GIT_TOKEN" to token,
|
||||
),
|
||||
)
|
||||
} finally {
|
||||
+1
-1
@@ -1,4 +1,4 @@
|
||||
package de.hoennig.gittally.git
|
||||
package de.hoennig.werkator.git
|
||||
|
||||
import org.springframework.stereotype.Component
|
||||
import java.nio.file.Path
|
||||
+3
-3
@@ -1,6 +1,6 @@
|
||||
package de.hoennig.gittally.git
|
||||
package de.hoennig.werkator.git
|
||||
|
||||
import de.hoennig.gittally.config.ConfigLoader
|
||||
import de.hoennig.werkator.config.ConfigLoader
|
||||
import org.slf4j.LoggerFactory
|
||||
import org.springframework.stereotype.Service
|
||||
import java.nio.file.Path
|
||||
@@ -260,7 +260,7 @@ class GitService(
|
||||
|
||||
/**
|
||||
* The content of [path] as committed in [commit], or null when that commit has no
|
||||
* such file — used to read a branch's committed `.gittally.yml` without a worktree.
|
||||
* such file — used to read a branch's committed `.werkator.yml` without a worktree.
|
||||
*/
|
||||
fun showFileAtCommit(
|
||||
commit: String,
|
||||
+6
-6
@@ -1,13 +1,13 @@
|
||||
package de.hoennig.gittally.gitea
|
||||
package de.hoennig.werkator.gitea
|
||||
|
||||
import com.fasterxml.jackson.core.JacksonException
|
||||
import com.fasterxml.jackson.core.type.TypeReference
|
||||
import com.fasterxml.jackson.databind.DeserializationFeature
|
||||
import com.fasterxml.jackson.databind.ObjectMapper
|
||||
import com.fasterxml.jackson.module.kotlin.registerKotlinModule
|
||||
import de.hoennig.gittally.build.BuildStatus
|
||||
import de.hoennig.gittally.config.ConfigLoader
|
||||
import de.hoennig.gittally.config.GitTallyConfig
|
||||
import de.hoennig.werkator.build.BuildStatus
|
||||
import de.hoennig.werkator.config.ConfigLoader
|
||||
import de.hoennig.werkator.config.WerkatorConfig
|
||||
import org.slf4j.LoggerFactory
|
||||
import org.springframework.http.MediaType
|
||||
import org.springframework.http.client.JdkClientHttpRequestFactory
|
||||
@@ -170,7 +170,7 @@ class GiteaClient(
|
||||
}
|
||||
}
|
||||
|
||||
private fun isEnabled(config: GitTallyConfig): Boolean =
|
||||
private fun isEnabled(config: WerkatorConfig): Boolean =
|
||||
config.gitea.baseUrl.isNotBlank() &&
|
||||
config.gitea.owner.isNotBlank() &&
|
||||
config.gitea.repo.isNotBlank() &&
|
||||
@@ -182,7 +182,7 @@ class GiteaClient(
|
||||
HttpClient.newBuilder().connectTimeout(REQUEST_TIMEOUT).build(),
|
||||
).apply { setReadTimeout(REQUEST_TIMEOUT) }
|
||||
|
||||
private fun restClient(config: GitTallyConfig): RestClient =
|
||||
private fun restClient(config: WerkatorConfig): RestClient =
|
||||
RestClient
|
||||
.builder()
|
||||
.requestFactory(requestFactory)
|
||||
+2
-2
@@ -1,6 +1,6 @@
|
||||
package de.hoennig.gittally.gitea
|
||||
package de.hoennig.werkator.gitea
|
||||
|
||||
import de.hoennig.gittally.build.BuildStatus
|
||||
import de.hoennig.werkator.build.BuildStatus
|
||||
|
||||
/**
|
||||
* Gitea commit-status state published for this build status.
|
||||
+2
-2
@@ -1,6 +1,6 @@
|
||||
package de.hoennig.gittally.metrics
|
||||
package de.hoennig.werkator.metrics
|
||||
|
||||
import de.hoennig.gittally.build.ArtifactStore
|
||||
import de.hoennig.werkator.build.ArtifactStore
|
||||
import org.springframework.context.annotation.Bean
|
||||
import org.springframework.context.annotation.Configuration
|
||||
import java.time.Clock
|
||||
+1
-1
@@ -1,4 +1,4 @@
|
||||
package de.hoennig.gittally.metrics
|
||||
package de.hoennig.werkator.metrics
|
||||
|
||||
import java.time.Instant
|
||||
|
||||
+3
-3
@@ -1,4 +1,4 @@
|
||||
package de.hoennig.gittally.metrics
|
||||
package de.hoennig.werkator.metrics
|
||||
|
||||
import com.fasterxml.jackson.databind.DeserializationFeature
|
||||
import com.fasterxml.jackson.databind.ObjectMapper
|
||||
@@ -30,7 +30,7 @@ data class PersistedMetricsState(
|
||||
* repository size every 60 seconds and keeps running min/max/avg per metric.
|
||||
* The aggregation state is persisted, so restarts continue the series.
|
||||
* Every source degrades gracefully: an unreadable source makes its metric null
|
||||
* (shown as `n/a`), never fails a sample. Like the [de.hoennig.gittally.watcher.Watcher],
|
||||
* (shown as `n/a`), never fails a sample. Like the [de.hoennig.werkator.watcher.Watcher],
|
||||
* nothing is scheduled until [start] is called (server mode only).
|
||||
*/
|
||||
class SystemMetricsCollector(
|
||||
@@ -83,7 +83,7 @@ class SystemMetricsCollector(
|
||||
scheduler =
|
||||
Executors
|
||||
.newSingleThreadScheduledExecutor { runnable ->
|
||||
Thread(runnable, "gittally-metrics").apply { isDaemon = true }
|
||||
Thread(runnable, "werkator-metrics").apply { isDaemon = true }
|
||||
}.also {
|
||||
it.scheduleWithFixedDelay(::sampleSafely, 0, SAMPLE_INTERVAL_SECONDS, TimeUnit.SECONDS)
|
||||
}
|
||||
+3
-3
@@ -1,7 +1,7 @@
|
||||
package de.hoennig.gittally.server
|
||||
package de.hoennig.werkator.server
|
||||
|
||||
import de.hoennig.gittally.build.BuildResult
|
||||
import de.hoennig.gittally.build.BuildStatus
|
||||
import de.hoennig.werkator.build.BuildResult
|
||||
import de.hoennig.werkator.build.BuildStatus
|
||||
import java.time.Instant
|
||||
|
||||
/** JSON statuses are lowercase like the legacy TSV/HTML statuses. */
|
||||
Some files were not shown because too many files have changed in this diff Show More
Reference in New Issue
Block a user