mi/werkator
1
0
Fork 0
Code Issues Pull Requests 1 Actions Packages Projects Releases Wiki Activity

renaming from gitTally to Werkator

Browse Source
This commit is contained in:
mhoennig
2026-08-30 18:35:49 +02:00
parent 4d76744721
commit 7f550689dd
169 changed files with 1361 additions and 7504 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.claude/skills/architecture/SKILL.md
+20 -20
View File
@@ -1,23 +1,23 @@
--- ---
name: architecture 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). It is a dual-mode application: **CLI** (interactive, status, config) and **Server** (HTTP, persistent).
## Entry Point and CLI Wiring ## 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 CliRunner ← CommandLineRunner + ExitCodeGenerator
GitTallyCommand ← root @Command, delegates to subcommands werkatorCommand ← root @Command, delegates to subcommands
commands/ commands/
InitCommand ← "init [--systemd]" InitCommand ← "init [--systemd]"
ServerCommand ← "server" ServerCommand ← "server"
@@ -31,27 +31,27 @@ 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. `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. 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 ## 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. 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 ## 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. 1. `.werkator.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`). 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`. 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`.
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. 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.
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". 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 `GitTallyConfig` data classes, the commented templates generated by `InitCommand`, and the reference in `docs/configuration.md`. 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 ## Git Access
@@ -59,16 +59,16 @@ Three places must stay in sync when config keys change: the `GitTallyConfig` dat
## Build Execution ## 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`). 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
`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. `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/gittally/auto-builds.json`; watcher health is exposed via `Watcher.state()`. 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 ## System Metrics
.claude/skills/writing-tests/SKILL.md
+3 -3
View File
@@ -1,9 +1,9 @@
--- ---
name: writing-tests 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. 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: Run a single test class instead of the full suite while iterating:
```bash ```bash
./gradlew test --tests "de.hoennig.gittally.ApplicationContextTest" ./gradlew test --tests "de.hoennig.werkator.ApplicationContextTest"
``` ```
## Mocking in Spring Slice Tests ## Mocking in Spring Slice Tests
.gitignore
+4 -1
View File
@@ -12,7 +12,7 @@
# Package Files # # Package Files #
*.jar *.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 !gradle/wrapper/gradle-wrapper.jar
*.war *.war
*.nar *.nar
@@ -31,3 +31,6 @@ replay_pid*
# Gradle # Gradle
.gradle/ .gradle/
/build/ /build/
# Other
/.local/
.gittally.yml
+3 -3
View File
@@ -1,13 +1,13 @@
server: 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: "" publicBaseUrl: ""
# Gitea integration for fetching commits and posting build statuses. # Gitea integration for fetching commits and posting build statuses.
gitea: gitea:
baseUrl: https://github.com # base URL of the Gitea instance baseUrl: https://github.com # base URL of the Gitea instance
owner: mhoennig # repository owner (user or organisation) for Gitea API (e.g. status checks) owner: mhoennig # repository owner (user or organisation) for Gitea API (e.g. status checks)
repo: gittally # repository name repo: werkator # 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 artifact retention. # Build artifact retention.
artifacts: artifacts:
AGENTS.md
+15 -15
View File
@@ -1,4 +1,4 @@
# GitTally — Agent Instructions # werkator — Agent Instructions
This file holds the shared, tool-agnostic instructions for all AI coding agents. 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. 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 build # compile + ktlintCheck + test
./gradlew ktlintFormat # auto-format before committing ./gradlew ktlintFormat # auto-format before committing
./gradlew test # run all tests (can be slow, prefer single test) ./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: Run the JAR directly:
```bash ```bash
java -jar build/libs/gittally.jar --help java -jar build/libs/werkator.jar --help
java -jar build/libs/gittally.jar init java -jar build/libs/werkator.jar init
``` ```
`ktlintFormat` must be run before `build` passes — the formatter is enforced as part of the `check` lifecycle. `ktlintFormat` must be run before `build` passes — the formatter is enforced as part of the `check` lifecycle.
## Architecture Overview ## 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). 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). 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 ### 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 ### Hard Invariants
- `exitProcess` is called only from `main()` — never inside `CliRunner.run()`; this keeps the Spring context alive during tests. - `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. - 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. - 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 `GitTallyConfig` data classes, the `InitCommand` templates, and `docs/configuration.md`. - 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 `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. - 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 `.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. - 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. - 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`. - 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. - `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. - Git and Docker access shells out to the CLIs (`GitCommandRunner`, `docker`) — no JGit, no Docker SDK.
## Testing ## Testing
@@ -61,11 +61,11 @@ Keep sentences short.
## Documentation ## 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/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 `GitTallyConfig` and the `init` templates. - `docs/configuration.md` — configuration reference; keep in sync with `WerkatorConfig` and the `init` templates.
- `docs/bootstrapping.md` — how `init` prepares a repository. - `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/deployment.md` — running werkator 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/migration-from-legacy.md` — legacy env vars → YAML keys mapping and the manual migration steps; `legacy/werkator` is deprecated.
- `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/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. - `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.
CLAUDE.md
+1 -1
View File
@@ -1,4 +1,4 @@
# GitTally — Claude Code Instructions # werkator — Claude Code Instructions
@AGENTS.md @AGENTS.md
README.md
+3 -3
View File
@@ -1,4 +1,4 @@
# GitTally # werkator
Lightweight, declarative and highly opinionated software build system (CI/CD). Lightweight, declarative and highly opinionated software build system (CI/CD).
@@ -6,12 +6,12 @@ Lightweight, declarative and highly opinionated software build system (CI/CD).
- [docs/configuration.md](docs/configuration.md) — configuration reference - [docs/configuration.md](docs/configuration.md) — configuration reference
- [docs/bootstrapping.md](docs/bootstrapping.md) — initializing a repository with `init` - [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/deployment.md](docs/deployment.md) — running werkator as a systemd service behind a reverse proxy
- [docs/migration-from-legacy.md](docs/migration-from-legacy.md) — migrating from the legacy bash script - [docs/migration-from-legacy.md](docs/migration-from-legacy.md) — migrating from the legacy bash script
## Legacy Script ## Legacy Script
`legacy/gitTally` (bash) is **deprecated** and kept only as a behavioral reference for the rewrite. `legacy/werkator` (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). Do not use it for new installations; see [docs/migration-from-legacy.md](docs/migration-from-legacy.md).
## Developer Setup ## Developer Setup
build.gradle.kts
+8 -8
View File
@@ -69,7 +69,7 @@ springBoot {
tasks.bootJar { tasks.bootJar {
// version-free jar name, so docs and scripts never contain the version; // version-free jar name, so docs and scripts never contain the version;
// the version itself stays available via BuildProperties (UI footer, --version) // the version itself stays available via BuildProperties (UI footer, --version)
archiveFileName = "gittally.jar" archiveFileName = "werkator.jar"
} }
kotlin { kotlin {
@@ -80,7 +80,7 @@ kotlin {
} }
// Self-contained runtime bundle for hosts without a Java runtime (plan step 15, ADR 0006): // 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 // The JDK module list below was computed from the exploded boot jar via
// jdeps -q --ignore-missing-deps --multi-release 21 --print-module-deps \ // jdeps -q --ignore-missing-deps --multi-release 21 --print-module-deps \
// --class-path 'BOOT-INF/lib/*' BOOT-INF/classes BOOT-INF/lib/*.jar // --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 jdkHome = javaToolchains.launcherFor(java.toolchain).map { it.metadata.installationPath.asFile }
val jarFile = tasks.bootJar.flatMap { it.archiveFile } 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 = val stagingDir =
layout.buildDirectory layout.buildDirectory
.dir("runtime-bundle") .dir("runtime-bundle")
@@ -123,7 +123,7 @@ val runtimeBundle by tasks.registering {
.asFile .asFile
val tarballFile = val tarballFile =
layout.buildDirectory layout.buildDirectory
.file("distributions/gittally-runtime-linux-x64.tar.gz") .file("distributions/werkator-runtime-linux-x64.tar.gz")
.get() .get()
.asFile .asFile
@@ -133,7 +133,7 @@ val runtimeBundle by tasks.registering {
outputs.file(tarballFile) outputs.file(tarballFile)
doLast { doLast {
val bundleRoot = stagingDir.resolve("gittally") val bundleRoot = stagingDir.resolve("werkator")
bundleRoot.deleteRecursively() bundleRoot.deleteRecursively()
bundleRoot.parentFile.mkdirs() bundleRoot.parentFile.mkdirs()
@@ -154,14 +154,14 @@ val runtimeBundle by tasks.registering {
val jlinkOutput = jlinkProcess.inputStream.bufferedReader().readText() val jlinkOutput = jlinkProcess.inputStream.bufferedReader().readText()
check(jlinkProcess.waitFor() == 0) { "jlink failed:\n$jlinkOutput" } check(jlinkProcess.waitFor() == 0) { "jlink failed:\n$jlinkOutput" }
jarFile.get().asFile.copyTo(bundleRoot.resolve("lib/gittally.jar").also { it.parentFile.mkdirs() }) jarFile.get().asFile.copyTo(bundleRoot.resolve("lib/werkator.jar").also { it.parentFile.mkdirs() })
val launcher = launcherFile.copyTo(bundleRoot.resolve("bin/gittally").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" } check(launcher.setExecutable(true, false)) { "cannot make $launcher executable" }
tarballFile.parentFile.mkdirs() tarballFile.parentFile.mkdirs()
// system tar preserves the execute bits of jre/bin/* and jre/lib/jspawnhelper // system tar preserves the execute bits of jre/bin/* and jre/lib/jspawnhelper
val tarProcess = val tarProcess =
ProcessBuilder("tar", "-czf", tarballFile.absolutePath, "-C", stagingDir.absolutePath, "gittally") ProcessBuilder("tar", "-czf", tarballFile.absolutePath, "-C", stagingDir.absolutePath, "werkator")
.redirectErrorStream(true) .redirectErrorStream(true)
.start() .start()
val tarOutput = tarProcess.inputStream.bufferedReader().readText() val tarOutput = tarProcess.inputStream.bufferedReader().readText()
docs/GitTally-Konzept.md → docs/Werkator-Konzept.md
+13 -13
View File
@@ -1,8 +1,8 @@
# GitTally – Konzept und Architekturübersicht # Werkator – Konzept und Architekturübersicht
## Motivation ## 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. 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 ### 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. 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`). 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). 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 ### 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 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 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. 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 1. Eingebaute Defaults
2. Globale Server-Konfiguration 2. Globale Server-Konfiguration
3. Repository-Installation (.git/gittally/.gittally.yml) 3. Repository-Installation (.git/werkator/.werkator.yml)
4. Projektkonfiguration (.gittally.yml) 4. Projektkonfiguration (.werkator.yml)
5. Branchprofile 5. Branchprofile
## Bootstrapping ## Bootstrapping
@@ -156,18 +156,18 @@ Ob ein neuer Commit den laufenden Build seines Branches stattdessen abbrechen so
- Java Runtime - Java Runtime
- Git Repository - Git Repository
- Ausgecheckter Workspace - Ausgecheckter Workspace
- GitTally JAR - Werkator JAR
### Initialisierung ### Initialisierung
```bash ```bash
java -jar build/libs/gittally.jar init java -jar build/libs/werkator.jar init
``` ```
### Serverstart ### Serverstart
```bash ```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`). 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 ### Konfigurationsanzeige
```bash ```bash
java -jar build/libs/gittally.jar config:print java -jar build/libs/werkator.jar config:print
java -jar build/libs/gittally.jar config:print --full java -jar build/libs/werkator.jar config:print --full
``` ```
## Erweiterungen ## 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 - SQLite statt Dateisystem
- Mehrere BuildWorker - Mehrere BuildWorker
- Multi-Repository-Verwaltung - Multi-Repository-Verwaltung
docs/adrs/0001-2026-06-09.test-framework.md
+1 -1
View File
@@ -10,7 +10,7 @@
## Context and Problem Statement ## 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. 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. The framework shapes how tests are structured, how readable they are, and how well they integrate with the Spring Boot test slice infrastructure.
docs/adrs/0002-2026-06-09.gradle-version.md
+1 -1
View File
@@ -10,7 +10,7 @@
## Context and Problem Statement ## 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. 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. [Gradle 9](https://docs.gradle.org/9.3.0/release-notes.html) (currently 9.5.1) is now stable and available.
docs/adrs/0003-2026-06-09.spring-boot-version.md
+1 -1
View File
@@ -10,7 +10,7 @@
## Context and Problem Statement ## 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. A Spring Boot version must be chosen for the initial setup.
The choice is constrained by the support lifecycle: as of June 2026, The choice is constrained by the support lifecycle: as of June 2026,
docs/adrs/0004-2026-07-07.rewrite-architecture.md
+4 -4
View File
@@ -10,7 +10,7 @@
## Context and Problem Statement ## 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. They were proposed in `docs/plan/README.md`, validated step by step during implementation, and are summarized here as one record.
### Technical Background ### Technical Background
@@ -26,7 +26,7 @@ Its two structural defects — build status not observable during a build, and a
### Persistence: JSON files behind `BuildResultRepository` ### 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 #### 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 ### 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 #### Advantages
@@ -64,7 +64,7 @@ nginx/Let's Encrypt container management was not ported; `init --systemd` genera
#### Disadvantages #### 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 ## Decision Outcome
docs/adrs/0005-2026-07-07.managed-nginx-tls.md
+9 -9
View File
@@ -6,7 +6,7 @@
- rejected: - - rejected: -
- superseded: - - 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 ## Context and Problem Statement
@@ -15,22 +15,22 @@ That decision was carried over from the rewrite plan without validating it again
### Technical Background ### Technical Background
GitTally must run on Hostsharing managed container environments. werkator 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. These hosts provide Docker but no root access and no host web server that werkator could sit behind.
Without the managed nginx container, GitTally cannot be served over HTTPS there at all. 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. 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 ## Considered Options
* Keep ADR 0004 as is (host reverse proxy only) * Keep ADR 0004 as is (host reverse proxy only)
* Re-add the legacy managed nginx+certbot container as an opt-in feature * 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 ### Host reverse proxy only
#### Advantages #### Advantages
- No container lifecycle or certificate code in GitTally. - No container lifecycle or certificate code in werkator.
#### Disadvantages #### 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 ### 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 #### Advantages
@@ -48,13 +48,13 @@ GitTally starts and supervises a labelled nginx container and handles certificat
#### Disadvantages #### Disadvantages
- Re-adds container lifecycle and certificate renewal complexity to GitTally. - Re-adds container lifecycle and certificate renewal complexity to werkator.
### External compose stack ### External compose stack
#### Advantages #### Advantages
- Keeps GitTally itself simple. - Keeps werkator itself simple.
#### Disadvantages #### Disadvantages
docs/adrs/0006-2026-08-10.runtime-bundle-distribution.md
+9 -9
View File
@@ -6,30 +6,30 @@
- rejected: - - rejected: -
- superseded: - - 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`. **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 GitTally runtime were rejected. The JAR stays the primary artifact; a GraalVM native image and a containerized werkator runtime were rejected.
## Context and Problem Statement ## 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. 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 ## Considered Options
* jlink runtime bundle (trimmed JRE + jar + launcher, one tarball) * jlink runtime bundle (trimmed JRE + jar + launcher, one tarball)
* GraalVM native image (single executable) * 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 ### 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: Good:
- No production-code changes and plain JVM semantics — no new failure modes. - 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. - 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. - Every JDK 21 ships jlink — no new build-toolchain requirement.
Bad: Bad:
@@ -44,12 +44,12 @@ Bad:
### GraalVM Native Image ### 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. 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. 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). 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. 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. This remains the documented fallback if the runtime bundle ever becomes unworkable.
docs/adrs/0007-2026-08-28.build-definitions.md
+3 -3
View File
@@ -11,7 +11,7 @@
## Context and Problem Statement ## 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. 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. 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: 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. - **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. - **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. - **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. 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. 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 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`). 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. 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.
docs/bootstrapping.md
+23 -23
View File
@@ -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). 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). 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` ## 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 ```bash
./gradlew build ./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`): Then run `init` using the generated JAR (not the `-plain.jar`):
```bash ```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: `init` performs the following steps in order:
### 1. Detect the Repository Root ### 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. If the current directory is not inside a git repository, `init` exits with an error.
### 2. Auto-detect Gitea Connection from `origin` ### 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 | | 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 ### 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, This file is **never committed** to the repository and is used for all branches,
as long as not overridden by a project config. as long as not overridden by a project config.
@@ -68,7 +68,7 @@ git:
### 4. Create the Branch/Project Config ### 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. 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 ## Output
`init` prints one line per action taken: `init` prints one line per action taken:
``` ```
created .git/gittally/.gittally.yml created .git/werkator/.werkator.yml
created .gittally.yml created .werkator.yml
``` ```
Or, when files already exist: Or, when files already exist:
``` ```
.git/gittally/.gittally.yml already exists — not overwritten .git/werkator/.werkator.yml already exists — not overwritten
.gittally.yml already exists — not overwritten .werkator.yml already exists — not overwritten
``` ```
## Hosts Without a Java Runtime ## 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. 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` ## Next Steps After `init`
1. Open `.git/gittally/.gittally.yml` and set `git.token` and `git.account`. 1. Open `.git/werkator/.werkator.yml` and set `git.token` and `git.account`.
2. Review `.gittally.yml` and add/adjust any branch build settings. 2. Review `.werkator.yml` and add/adjust any branch build settings.
3. Verify the effective configuration: 3. Verify the effective configuration:
```bash ```bash
java -jar build/libs/gittally.jar config:print --full java -jar build/libs/werkator.jar config:print --full
``` ```
4. Start the server: 4. Start the server:
```bash ```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). 5. For permanent operation, install the systemd user service described in [deployment.md](deployment.md).
## Example: Test Server with a Fake Build ## 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. 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. 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. 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. 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. 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. `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. 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.
docs/configuration.md
+52 -52
View File
@@ -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 ## Config File Locations
| Layer | Path | Committed to Git | Purpose | | Layer | Path | Committed to Git | Purpose |
|--------------------------|----------------------------|------------------|----------------------------------------------| |--------------------------|----------------------------|------------------|----------------------------------------------|
| Project config | `.gittally.yml` | Yes | Shared team settings | | Project config | `.werkator.yml` | Yes | Shared team settings |
| Repo installation config | `.git/gittally/.gittally.yml` | No | Machine- or user-specific overrides, secrets | | Repo installation config | `.git/werkator/.werkator.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 | | 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 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. understands, and the effect shows up as a build that does the wrong thing.
```yaml ```yaml
gitTally: werkator:
version: version:
since: "0.9.16" # enforced: an older GitTally refuses to read this file since: "0.9.16" # enforced: an older werkator refuses to read this file
below: "2.0" # your release marker; GitTally decides how strictly to take it 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 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 ever supported. The declaration exists to make an incompatibility nameable, never to run
two parsers. two parsers.
`since` is a hard floor and covers both directions: `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 — - 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 werkator 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 name the change: *"is written for werkator 1.4.0, but the configuration format changed
incompatibly in 2.0.0: `builds:` is now `buildSpec:`"*. incompatibly in 2.0.0: `builds:` is now `buildSpec:`"*.
`below` is optional and names the first version this file was **not** released for. The `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 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 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 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 try it (on a test host, or in production with a rollback ready), and then raise `below` and
commit that. commit that.
A file that declares nothing is read as before, with a hint in the log — a missing line 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. generated config.
How far a violation reaches depends on the file, following the same rule as everything 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 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 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 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 definitions and its overrides of the definitions from the project config, with
@@ -95,7 +95,7 @@ single branch may decide it:
configuration does. configuration does.
The distinction is documentary. 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. value then resolves from whichever remaining layer sets it.
The names say where a key is meant to live, not how it is enforced. 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 ## Inspect the Effective Config
```bash ```bash
java -jar build/libs/gittally.jar config:print # only explicitly set values java -jar build/libs/werkator.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 --full # all values including defaults
``` ```
`git.token` is masked as `***` by default, so the output can safely be shared or pasted. `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. Add `--show-secrets` to print it in clear text.
## `.gittally.yml` ## `.werkator.yml`
Values shown are the defaults. Values shown are the defaults.
```yaml ```yaml
# The GitTally this file is written for (see the section above). # The werkator this file is written for (see the section above).
gitTally: werkator:
version: 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 below: "2.0" # optional release marker; warns, does not block
server: 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/ publicBaseUrl: https://ci.example.org/
# HTTP port of the `server` subcommand (default 18080, like legacy) # HTTP port of the `server` subcommand (default 18080, like legacy)
port: 18080 port: 18080
@@ -151,10 +151,10 @@ server:
httpsPort: 8443 httpsPort: 8443
# host nginx proxies to; empty = serverName (the container cannot reach localhost) # host nginx proxies to; empty = serverName (the container cannot reach localhost)
upstreamHost: "" upstreamHost: ""
# name of the managed container; empty = gittally-nginx-<repo-name> # name of the managed container; empty = werkator-nginx-<repo-name>
containerName: "" containerName: ""
# directory for nginx config, certificates, and logs; # 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: "" stateDir: ""
# e-mail for the Let's Encrypt account; empty registers without one # e-mail for the Let's Encrypt account; empty registers without one
letsencryptEmail: "" letsencryptEmail: ""
@@ -164,14 +164,14 @@ gitea:
baseUrl: https://git.example.org # base URL of the Gitea instance 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) owner: my-org # repository owner (user or organisation) for Gitea API (e.g. status checks)
repo: my-repo # repository name 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 # Build execution settings, enforced for all builds regardless of their trigger
# (watcher, UI restart, CLI build/retry). # (watcher, UI restart, CLI build/retry).
executor: executor:
# How many builds may run at the same time. # How many builds may run at the same time.
# At most one build per branch runs regardless; each branch builds in its own # 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. # Changing this value requires a restart.
maxConcurrent: 1 maxConcurrent: 1
@@ -233,12 +233,12 @@ builds:
activeWithin: 24h activeWithin: 24h
buildCommand: ./gradlew -PfullPitTest --console=plain --no-daemon piTestFull buildCommand: ./gradlew -PfullPitTest --console=plain --no-daemon piTestFull
artifactDirs: [build/reports, build/libs] artifactDirs: [build/reports, build/libs]
statusContext: GitTally/pitest statusContext: werkator/pitest
# Build artifact storage and retention. # Build artifact storage and retention.
artifacts: artifacts:
# Root directory for stored build 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. # where <repo-key> is the sanitized absolute repository path.
# A leading ~/ expands to the home directory; a relative path is resolved against the repository. # A leading ~/ expands to the home directory; a relative path is resolved against the repository.
rootDir: "" rootDir: ""
@@ -275,24 +275,24 @@ watcher:
### Notes on `server.bindAddress` ### Notes on `server.bindAddress`
The default is `127.0.0.1`. 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. 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 GitTally over the Docker bridge, not over loopback), or when the proxy runs on another host. 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 `.gittally.yml` and keep it; the new default only applies where the key is absent or `init` writes a fresh file. 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` ### 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). 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). 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>/`. 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. 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`. `server.port` must differ from `httpPort` and `httpsPort`.
### Notes on `builds.<name>.requirePullRequest` ### Notes on `builds.<name>.requirePullRequest`
The gate applies to all watcher-triggered builds (push-triggered and scheduled auto builds). 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: 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. 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. 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. 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) ### 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. 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. 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. 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. 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. 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. Both parts combine as an intersection.
Settings: `buildCommand`, `cleanCommand`, `artifactDirs`, `stdoutLog`/`stderrLog`, `requirePullRequest`, `statusContext`, and `docker` with all its keys. 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. `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. 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. 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 `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 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. 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 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. 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. 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` ### Notes on `watcher.fastForwardLocalRefs`
Builds run in worktrees that share the primary checkout's `.git`, so a build tool can read `refs/heads/*` there. 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. 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. 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` ### 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. 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`. Staleness is tracked via the image label `org.werkator.build-inputs-sha256`.
A Gradle cache volume `gittally-gradle-<repo-key>` is created per repository and mounted as `GRADLE_USER_HOME`. 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. 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. 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; GitTally never stores credentials there, and neither should you. 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. 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 ```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: git:
account: my-user # technical username for git HTTPS authentication account: my-user # technical username for git HTTPS authentication
token: glpat-xxxxxxxxxxxxxxxxxxxx # Gitea API token — never commit this token: glpat-xxxxxxxxxxxxxxxxxxxx # Gitea API token — never commit this
docs/deployment.md
+60 -60
View File
@@ -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. 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). 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 ## Prerequisites
@@ -19,14 +19,14 @@ Build the executable jar once:
```bash ```bash
./gradlew build ./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 ```bash
mkdir -p ~/bin 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`. 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 ## 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 ```bash
cd /path/to/repo cd /path/to/repo
java -jar ~/bin/gittally.jar init java -jar ~/bin/werkator.jar init
# fill in git.account and git.token in .git/gittally/.gittally.yml # fill in git.account and git.token in .git/werkator/.werkator.yml
# review .gittally.yml # review .werkator.yml
``` ```
Generate the systemd user unit: Generate the systemd user unit:
```bash ```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 ```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/werkator/werkator-<repo-name>.service ~/.config/systemd/user/werkator-<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/werkator/werkator-docker-prune.service ~/.config/systemd/user/werkator-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-docker-prune.timer ~/.config/systemd/user/werkator-docker-prune.timer
systemctl --user daemon-reload systemctl --user daemon-reload
systemctl --user enable --now gittally-<repo-name>.service systemctl --user enable --now werkator-<repo-name>.service
systemctl --user enable --now gittally-docker-prune.timer 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. 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 ### 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. 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. 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`). On hosts without a `docker` CLI the service is skipped, not failed (`ExecCondition`).
`Persistent=true` catches up a missed run after downtime. `Persistent=true` catches up a missed run after downtime.
@@ -84,10 +84,10 @@ loginctl enable-linger "$USER"
## Operating the Service ## Operating the Service
```bash ```bash
systemctl --user status gittally-<repo-name>.service # state and last log lines systemctl --user status werkator-<repo-name>.service # state and last log lines
journalctl --user -u gittally-<repo-name>.service -f # follow the log journalctl --user -u werkator-<repo-name>.service -f # follow the log
systemctl --user restart gittally-<repo-name>.service # restart (e.g. after config changes) systemctl --user restart werkator-<repo-name>.service # restart (e.g. after config changes)
systemctl --user stop gittally-<repo-name>.service # stop systemctl --user stop werkator-<repo-name>.service # stop
``` ```
## Updating an Existing Installation ## Updating an Existing Installation
@@ -103,67 +103,67 @@ With a jar installation:
```bash ```bash
./gradlew build # on the dev machine ./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> ssh <user>@<host>
systemctl --user stop gittally-<repo-name>.service systemctl --user stop werkator-<repo-name>.service
mv ~/bin/gittally.jar ~/bin/gittally.jar.bak # rollback copy mv ~/bin/werkator.jar ~/bin/werkator.jar.bak # rollback copy
mv ~/bin/gittally.jar.new ~/bin/gittally.jar mv ~/bin/werkator.jar.new ~/bin/werkator.jar
systemctl --user start gittally-<repo-name>.service systemctl --user start werkator-<repo-name>.service
systemctl --user is-active gittally-<repo-name>.service systemctl --user is-active werkator-<repo-name>.service
``` ```
With a runtime bundle (hosts without Java, see below): With a runtime bundle (hosts without Java, see below):
```bash ```bash
./gradlew runtimeBundle # on the dev machine ./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> ssh <user>@<host>
systemctl --user stop gittally-<repo-name>.service systemctl --user stop werkator-<repo-name>.service
mv ~/opt/gittally ~/opt/gittally.bak # rollback copy mv ~/opt/werkator ~/opt/werkator.bak # rollback copy
tar xzf /tmp/gittally-new.tar.gz -C /tmp/ && mv /tmp/gittally ~/opt/gittally tar xzf /tmp/werkator-new.tar.gz -C /tmp/ && mv /tmp/werkator ~/opt/werkator
~/opt/gittally/bin/gittally --version # expected: the new version ~/opt/werkator/bin/werkator --version # expected: the new version
systemctl --user start gittally-<repo-name>.service systemctl --user start werkator-<repo-name>.service
systemctl --user is-active gittally-<repo-name>.service systemctl --user is-active werkator-<repo-name>.service
rm -f /tmp/gittally-new.tar.gz 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. 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. Config file changes are not needed for an update; new keys take their defaults.
## Control Token ## 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. 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`). 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/gittally/control-token`, a random secret the server generates on first start (mode `0600`; delete the file to rotate it). 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 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. 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: Read it on the host:
```bash ```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: 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 ```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" "https://ci.example.org/api/builds/restart?branch=main"
``` ```
## Environment File ## 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`. 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. `init --systemd` never overwrites an existing environment file.
## Reverse Proxy (nginx) ## 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 ```yaml
server: 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) ## 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. 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: Build the bundle on a Linux x86_64 machine whose glibc is not newer than the target's:
```bash ```bash
./gradlew runtimeBundle ./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 ```bash
scp build/distributions/gittally-runtime-linux-x64.tar.gz user@host:/tmp/ scp build/distributions/werkator-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' 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 ```bash
cd /path/to/repo cd /path/to/repo
~/opt/gittally/bin/gittally init ~/opt/werkator/bin/werkator init
~/opt/gittally/bin/gittally init --systemd ~/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. `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) ## 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. 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. 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: Enable it in the server section of the configuration:
@@ -252,12 +252,12 @@ server:
letsencryptEmail: admin@example.org 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. A renewal check runs daily; certificates and nginx state persist in `server.nginx.stateDir` across restarts.
On shutdown the container is removed. On shutdown the container is removed.
All nginx and certificate failures are non-fatal warnings — the plain HTTP server keeps running without the proxy. 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. `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. 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. See [configuration.md](configuration.md) for all `server.nginx.*` keys.
docs/examples/setup-gittally-selfhost.sh
+19 -19
View File
@@ -1,13 +1,13 @@
#!/usr/bin/env bash #!/usr/bin/env bash
# Example: set up a GitTally instance that watches and builds GitTally itself. # Example: set up a werkator instance that watches and builds werkator itself.
# Run from inside a working checkout of the gittally repository. # Run from inside a working checkout of the werkator repository.
# #
# Usage: # 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) # (both empty is fine for a public origin — commit statuses just won't be published)
set -euo pipefail 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_ACCOUNT="${GIT_ACCOUNT:-}" # technical Gitea user for HTTPS fetch + status API
GIT_TOKEN="${GIT_TOKEN:-}" # Gitea API token — stays in the uncommitted config file GIT_TOKEN="${GIT_TOKEN:-}" # Gitea API token — stays in the uncommitted config file
SERVER_PORT="${SERVER_PORT:-18080}" SERVER_PORT="${SERVER_PORT:-18080}"
@@ -15,45 +15,45 @@ SERVER_PORT="${SERVER_PORT:-18080}"
DEV_CHECKOUT=$(git rev-parse --show-toplevel) DEV_CHECKOUT=$(git rev-parse --show-toplevel)
ORIGIN_URL="${ORIGIN_URL:-$(git -C "$DEV_CHECKOUT" remote get-url origin)}" 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) (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. # completely separate from your dev checkout.
mkdir -p "$INSTALL_DIR" 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 if [ ! -d "$INSTALL_DIR/repo/.git" ]; then
git clone "$ORIGIN_URL" "$INSTALL_DIR/repo" git clone "$ORIGIN_URL" "$INSTALL_DIR/repo"
fi fi
cd "$INSTALL_DIR/repo" cd "$INSTALL_DIR/repo"
# 3. Generate the config templates; existing files are kept. The clone already # 3. Generate the config templates; existing files are kept. The clone already
# carries the committed .gittally.yml, so this only creates the machine config # carries the committed .werkator.yml, so this only creates the machine config
# (.git/gittally/.gittally.yml). # (.git/werkator/.werkator.yml).
java -jar "$INSTALL_DIR/gittally.jar" init java -jar "$INSTALL_DIR/werkator.jar" init
# 4. Machine-specific overrides and secrets (.git/gittally/ is never committed; # 4. Machine-specific overrides and secrets (.git/werkator/ is never committed;
# this file deep-merges over .gittally.yml and wins). # this file deep-merges over .werkator.yml and wins).
cat > .git/gittally/.gittally.yml <<EOF cat > .git/werkator/.werkator.yml <<EOF
git: git:
account: "$GIT_ACCOUNT" account: "$GIT_ACCOUNT"
token: "$GIT_TOKEN" token: "$GIT_TOKEN"
server: server:
port: $SERVER_PORT port: $SERVER_PORT
EOF 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 # buildCommand: ./gradlew --console=plain --no-daemon test
# artifactDirs: [build/reports] # artifactDirs: [build/reports]
# 5. Optional kick-start: put the local ref one commit behind origin so the very # 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. # Builds never move this ref or touch this checkout, so lagging is harmless.
git reset --hard --quiet HEAD~1 || true git reset --hard --quiet HEAD~1 || true
# 6. Run it (Ctrl-C stops it cleanly). For a permanent setup, run # 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. # docs/deployment.md — the generated unit points at this jar and repo.
echo "GitTally self-host: http://localhost:$SERVER_PORT/ — watching $ORIGIN_URL" echo "werkator self-host: http://localhost:$SERVER_PORT/ — watching $ORIGIN_URL"
exec java -jar "$INSTALL_DIR/gittally.jar" server exec java -jar "$INSTALL_DIR/werkator.jar" server
docs/examples/setup-gittally-testserver.sh
+14 -14
View File
@@ -1,30 +1,30 @@
#!/usr/bin/env bash #!/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: # 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 # 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 # build with live log output and a demo report artifact, and a fast poll
# interval — no Gitea, no credentials, no Docker. # interval — no Gitea, no credentials, no Docker.
# #
# Usage: # Usage:
# ./docs/examples/setup-gittally-testserver.sh # ./docs/examples/setup-werkator-testserver.sh
# BUILD_SECONDS=5 SERVER_PORT=18981 ./docs/examples/setup-gittally-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: # 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; # A commit message containing "[fail]" makes the fake build fail;
# pushing a new branch exercises the new-origin-branch path. # pushing a new branch exercises the new-origin-branch path.
set -euo pipefail set -euo pipefail
INSTALL_DIR="${INSTALL_DIR:-$HOME/gittally-testserver}" INSTALL_DIR="${INSTALL_DIR:-$HOME/werkator-testserver}"
SERVER_PORT="${SERVER_PORT:-18980}" SERVER_PORT="${SERVER_PORT:-18980}"
export BUILD_SECONDS="${BUILD_SECONDS:-25}" # inherited by the build process at runtime export BUILD_SECONDS="${BUILD_SECONDS:-25}" # inherited by the build process at runtime
DEV_CHECKOUT=$(git rev-parse --show-toplevel) DEV_CHECKOUT=$(git rev-parse --show-toplevel)
# 1. Build the GitTally jar. # 1. Build the werkator jar.
(cd "$DEV_CHECKOUT" && ./gradlew --console=plain build) (cd "$DEV_CHECKOUT" && ./gradlew --console=plain build)
mkdir -p "$INSTALL_DIR" 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. # 2. Scratch bare origin plus a "work" clone for triggering builds by pushing.
if [ ! -d "$INSTALL_DIR/origin.git" ]; then 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' cat > "$INSTALL_DIR/work/fake-build.sh" <<'EOF'
#!/usr/bin/env bash #!/usr/bin/env bash
# Fake build: visible progress for the live log, then a demo report artifact. # 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 set -euo pipefail
echo "fake build of branch ${branch:-unknown} at commit $(git rev-parse --short HEAD)" echo "fake build of branch ${branch:-unknown} at commit $(git rev-parse --short HEAD)"
if git log -1 --pretty=%s | grep -qF '[fail]'; then 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" echo "fake build done"
EOF EOF
chmod +x "$INSTALL_DIR/work/fake-build.sh" chmod +x "$INSTALL_DIR/work/fake-build.sh"
cat > "$INSTALL_DIR/work/.gittally.yml" <<'EOF' cat > "$INSTALL_DIR/work/.werkator.yml" <<'EOF'
watcher: watcher:
pollInterval: 5s pollInterval: 5s
@@ -67,7 +67,7 @@ branches:
artifactDirs: artifactDirs:
- build/reports - build/reports
EOF 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 -m "fake build setup"
git -C "$INSTALL_DIR/work" commit --quiet --allow-empty -m "kick-start build" git -C "$INSTALL_DIR/work" commit --quiet --allow-empty -m "kick-start build"
git -C "$INSTALL_DIR/work" push --quiet origin main 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" git clone --quiet "$INSTALL_DIR/origin.git" "$INSTALL_DIR/repo"
fi fi
cd "$INSTALL_DIR/repo" cd "$INSTALL_DIR/repo"
mkdir -p .git/gittally mkdir -p .git/werkator
cat > .git/gittally/.gittally.yml <<EOF cat > .git/werkator/.werkator.yml <<EOF
server: server:
port: $SERVER_PORT port: $SERVER_PORT
bindAddress: 127.0.0.1 bindAddress: 127.0.0.1
@@ -101,8 +101,8 @@ git reset --hard --quiet HEAD~1 || true
# 5. Run it (Ctrl-C stops it cleanly). # 5. Run it (Ctrl-C stops it cleanly).
echo 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 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 "Trigger a failure: same with commit message 'trigger [fail]'"
echo echo
exec java -jar "$INSTALL_DIR/gittally.jar" server exec java -jar "$INSTALL_DIR/werkator.jar" server
docs/migration-from-legacy.md
+43 -43
View File
@@ -1,60 +1,60 @@
# Migration from the Legacy Script # Migration from the Legacy Script
The bash script `legacy/gitTally` is deprecated and replaced by this application. The bash script `legacy/werkator` 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. 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. See [configuration.md](configuration.md) for the full configuration reference and [deployment.md](deployment.md) for the new service setup.
## Configuration Mapping ## Configuration Mapping
Legacy configuration came from environment variables (`gitTally --env` template, sourced env files). Legacy configuration came from environment variables (`werkator --env` template, sourced env files).
The new configuration lives in two YAML files: `.gittally.yml` (committed) and `.git/gittally/.gittally.yml` (machine-specific, secrets). The new configuration lives in two YAML files: `.werkator.yml` (committed) and `.git/werkator/.werkator.yml` (machine-specific, secrets).
Build-level keys below live in a build definition under `builds.<name>`; use `builds.default` for what used to be 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. the global value — it is the base every other definition inherits its settings from.
| Legacy environment variable | New YAML key | | Legacy environment variable | New YAML key |
|---|---| |---|---|
| `GITTALLY_BUILD_COMMAND` | `builds.<name>.buildCommand` | | `werkator_BUILD_COMMAND` | `builds.<name>.buildCommand` |
| `GITTALLY_BUILD_CLEAN_COMMAND` | `builds.<name>.cleanCommand` | | `werkator_BUILD_CLEAN_COMMAND` | `builds.<name>.cleanCommand` |
| `GITTALLY_BUILD_ARTEFACT_DIRS` | `builds.<name>.artifactDirs` — YAML list instead of `;`-separated | | `werkator_BUILD_ARTEFACT_DIRS` | `builds.<name>.artifactDirs` — YAML list instead of `;`-separated |
| `GITTALLY_BUILD_STDOUT_LOG` | `builds.<name>.stdoutLog` | | `werkator_BUILD_STDOUT_LOG` | `builds.<name>.stdoutLog` |
| `GITTALLY_BUILD_STDERR_LOG` | `builds.<name>.stderrLog` | | `werkator_BUILD_STDERR_LOG` | `builds.<name>.stderrLog` |
| `GITTALLY_NEW_BRANCH_COMMIT_MAX_AGE` | `watcher.newBranchMaxAge` | | `werkator_NEW_BRANCH_COMMIT_MAX_AGE` | `watcher.newBranchMaxAge` |
| `GITTALLY_BUILD_DOCKER_IMAGE` | `builds.<name>.docker.image` — also set `docker.enabled: true` (replaces the `--docker` flag) | | `werkator_BUILD_DOCKER_IMAGE` | `builds.<name>.docker.image` — also set `docker.enabled: true` (replaces the `--docker` flag) |
| `GITTALLY_BUILD_DOCKERFILE` | `builds.<name>.docker.dockerfile` | | `werkator_BUILD_DOCKERFILE` | `builds.<name>.docker.dockerfile` |
| `GITTALLY_BUILD_DOCKER_CONTEXT` | `builds.<name>.docker.context` | | `werkator_BUILD_DOCKER_CONTEXT` | `builds.<name>.docker.context` |
| `GITTALLY_BUILD_DOCKER_NETWORK` | `builds.<name>.docker.network` — default is now Docker's default network, not `host` | | `werkator_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 | | `werkator_BUILD_DOCKER_ENV` | `builds.<name>.docker.env` — YAML map instead of space-separated assignments |
| `GITTALLY_ARTIFACT_SERVER_PORT` | `server.port` | | `werkator_ARTIFACT_SERVER_PORT` | `server.port` |
| `GITTALLY_ARTIFACT_SERVER_BIND_ADDRESS` | `server.bindAddress` | | `werkator_ARTIFACT_SERVER_BIND_ADDRESS` | `server.bindAddress` |
| `GITTALLY_ARTIFACT_PUBLIC_BASE_URL` | `server.publicBaseUrl` | | `werkator_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 | | `werkator_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` | | `werkator_IMPRESSUM_URL` | `server.impressumUrl` |
| `GITTALLY_AUTO_BUILD_BRANCHES` | a build definition with `branches: [...]` selecting them | | `werkator_AUTO_BUILD_BRANCHES` | a build definition with `branches: [...]` selecting them |
| `GITTALLY_AUTO_BUILD_TIMES` | `builds.<name>.atTimes` — YAML list of UTC `HH:MM` slots | | `werkator_AUTO_BUILD_TIMES` | `builds.<name>.atTimes` — YAML list of UTC `HH:MM` slots |
| `GITTALLY_GITEA_BASE_URL` | `gitea.baseUrl` | | `werkator_GITEA_BASE_URL` | `gitea.baseUrl` |
| `GITTALLY_GITEA_OWNER` | `gitea.owner` | | `werkator_GITEA_OWNER` | `gitea.owner` |
| `GITTALLY_GITEA_REPO` | `gitea.repo` | | `werkator_GITEA_REPO` | `gitea.repo` |
| `GITTALLY_GITEA_STATUS_CONTEXT` | `gitea.statusContext` | | `werkator_GITEA_STATUS_CONTEXT` | `gitea.statusContext` |
| `GITTALLY_GITEA_GIT_USERNAME` | `git.account` — in `.git/gittally/.gittally.yml` | | `werkator_GITEA_GIT_USERNAME` | `git.account` — in `.git/werkator/.werkator.yml` |
| `GITTALLY_GITEA_TOKEN` | `git.token` — in `.git/gittally/.gittally.yml`, never committed | | `werkator_GITEA_TOKEN` | `git.token` — in `.git/werkator/.werkator.yml`, never committed |
| `GITTALLY_ARTIFACT_NGINX_SERVER_NAME` | `server.nginx.serverName` — also set `server.nginx.enabled: true` (replaces the `--nginx` flag) | | `werkator_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` | | `werkator_ARTIFACT_NGINX_HTTP_PORT` | `server.nginx.httpPort` |
| `GITTALLY_ARTIFACT_NGINX_HTTPS_PORT` | `server.nginx.httpsPort` | | `werkator_ARTIFACT_NGINX_HTTPS_PORT` | `server.nginx.httpsPort` |
| `GITTALLY_ARTIFACT_NGINX_UPSTREAM_HOST` | `server.nginx.upstreamHost` | | `werkator_ARTIFACT_NGINX_UPSTREAM_HOST` | `server.nginx.upstreamHost` |
| `GITTALLY_ARTIFACT_NGINX_CONTAINER_NAME` | `server.nginx.containerName` | | `werkator_ARTIFACT_NGINX_CONTAINER_NAME` | `server.nginx.containerName` |
| `GITTALLY_ARTIFACT_NGINX_STATE_DIR` | `server.nginx.stateDir` | | `werkator_ARTIFACT_NGINX_STATE_DIR` | `server.nginx.stateDir` |
| `GITTALLY_ARTIFACT_LETSENCRYPT_EMAIL` | `server.nginx.letsencryptEmail` | | `werkator_ARTIFACT_LETSENCRYPT_EMAIL` | `server.nginx.letsencryptEmail` |
New keys without a legacy counterpart: `builds.maxConcurrent`, `artifacts.rootDir`, and `watcher.pollInterval`. New keys without a legacy counterpart: `builds.maxConcurrent`, `artifacts.rootDir`, and `watcher.pollInterval`.
## Intentionally Not Ported ## Intentionally Not Ported
- Self-install and self-update (`--install`, `--pull`, `GITTALLY_INSTALL_DIR`) — replaced by jar deployment plus `init --systemd`. - Self-install and self-update (`--install`, `--pull`, `werkator_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. - `werkator_BUILD_DOCKER_PREFLIGHT_COMMAND` and `werkator_BUILD_DOCKER_JAVA_TOOL_OPTIONS` — hsadmin-ng-specific; use `builds.<name>.docker.env` if needed.
- `HSADMIN_NG_*` environment-variable fallbacks. - `HSADMIN_NG_*` environment-variable fallbacks.
- Env-file configuration itself — the systemd `EnvironmentFile` now only tunes the JVM (`JAVA_OPTS`). - 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. - `werkator_GITEA_DELETED_STATUS_DESCRIPTION`, `werkator_BIN_FORWARD`, `werkator_CONFIG_*` — internal legacy mechanics without a counterpart.
## Build History ## Build History
@@ -80,15 +80,15 @@ curl -X POST -H "Authorization: token $TOKEN" -H 'Content-Type: application/json
1. Stop and remove the legacy service: 1. Stop and remove the legacy service:
```bash ```bash
systemctl --user disable --now gitTally.service systemctl --user disable --now werkator.service
rm -f ~/.config/systemd/user/gitTally.service rm -f ~/.config/systemd/user/werkator.service
systemctl --user daemon-reload systemctl --user daemon-reload
``` ```
2. Build and place the jar as described in [deployment.md](deployment.md). 2. Build and place the jar as described in [deployment.md](deployment.md).
3. In the repository, run `java -jar ~/bin/gittally.jar init`. 3. In the repository, run `java -jar ~/bin/werkator.jar init`.
4. Transfer your settings from the legacy env file into `.gittally.yml` using the table above. 4. Transfer your settings from the legacy env file into `.werkator.yml` using the table above.
5. Put `git.account` and `git.token` into `.git/gittally/.gittally.yml`. 5. Put `git.account` and `git.token` into `.git/werkator/.werkator.yml`.
6. Verify the effective configuration: `java -jar ~/bin/gittally.jar config:print --full`. 6. Verify the effective configuration: `java -jar ~/bin/werkator.jar config:print --full`.
7. Install and start the new service: `init --systemd` plus the printed commands, see [deployment.md](deployment.md). 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. 8. Optionally clean up legacy state: `.git/git-watch-origin-and-test/` and the legacy artifact root.
docs/plan/00-legacy-analysis.md
+6 -6
View File
@@ -1,6 +1,6 @@
# Legacy gitTally Analysis # Legacy werkator Analysis
Condensed analysis of `legacy/gitTally` (bash, ~6000 lines) as input for the rewrite. Condensed analysis of `legacy/werkator` (bash, ~6000 lines) as input for the rewrite.
Line numbers refer to the legacy script at the time of analysis (version 0.7.8). Line numbers refer to the legacy script at the time of analysis (version 0.7.8).
## What the Legacy System Does ## What the Legacy System Does
@@ -90,7 +90,7 @@ No status changes observable during a build (control loop):
Verify need before porting any of these: Verify need before porting any of these:
- `GITTALLY_BUILD_DOCKER_PREFLIGHT_COMMAND`, `GITTALLY_BUILD_DOCKER_JAVA_TOOL_OPTIONS` — highly hsadmin-ng-specific defaults. - `werkator_BUILD_DOCKER_PREFLIGHT_COMMAND`, `werkator_BUILD_DOCKER_JAVA_TOOL_OPTIONS` — highly hsadmin-ng-specific defaults.
- `GITTALLY_ARTIFACT_NGINX_*`, `GITTALLY_ARTIFACT_LETSENCRYPT_EMAIL` — dropped with nginx management; revived as `server.nginx.*` by step 13 (ADR 0005). - `werkator_ARTIFACT_NGINX_*`, `werkator_ARTIFACT_LETSENCRYPT_EMAIL` — dropped with nginx management; revived as `server.nginx.*` by step 13 (ADR 0005).
- `GITTALLY_IMPRESSUM_URL` — keep as optional simple footer link if wanted. - `werkator_IMPRESSUM_URL` — keep as optional simple footer link if wanted.
- `GITTALLY_INSTALL_DIR` — dropped with self-install. - `werkator_INSTALL_DIR` — dropped with self-install.
docs/plan/01-build-state-domain.md
+3 -3
View File
@@ -9,14 +9,14 @@ A tested domain model for build results plus a persistent repository, replacing
## Design ## Design
Create package `de.hoennig.gittally.build`: Create package `de.hoennig.werkator.build`:
- `BuildStatus` enum: `PENDING`, `RUNNING`, `SUCCESS`, `FAILED`, `INTERRUPTED`, `CANCELLED`. - `BuildStatus` enum: `PENDING`, `RUNNING`, `SUCCESS`, `FAILED`, `INTERRUPTED`, `CANCELLED`.
Add `isTerminal`, `isRestartable` (pending/running/interrupted) properties. Add `isTerminal`, `isRestartable` (pending/running/interrupted) properties.
- `BuildResult` data class: branch, commit SHA, status, startedAt, duration, artifactKey. - `BuildResult` data class: branch, commit SHA, status, startedAt, duration, artifactKey.
Use `java.time.Instant`/`Duration`; format only at the edges. 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. - `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`). Write atomically (write temp file, then `Files.move` with `ATOMIC_MOVE`).
Reuse the Jackson YAML/JSON setup style from `ConfigLoader`. 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) ## 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: Deviations and details:
- Added `jackson-datatype-jsr310` to `build.gradle.kts` for `Instant`/`Duration` JSON support (ISO-8601 strings). - Added `jackson-datatype-jsr310` to `build.gradle.kts` for `Instant`/`Duration` JSON support (ISO-8601 strings).
docs/plan/03-gitea-client.md
+4 -4
View File
@@ -9,7 +9,7 @@ A tested client for the Gitea commit-status API.
## Design ## Design
Create package `de.hoennig.gittally.gitea`: Create package `de.hoennig.werkator.gitea`:
- `GiteaClient` using Spring's `RestClient`. - `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`. - `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. - `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. 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 ## Out of Scope
- No callers yet; the build executor (step 04) wires status publishing. - 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 ## 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. - `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. - 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. - 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`.
docs/plan/04-build-executor.md
+6 -6
View File
@@ -10,7 +10,7 @@ This step fixes the legacy defect that nothing could observe status changes whil
## Design ## 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). - `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?`. - `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) ## 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). (`BuildExecutorTest`, `ProcessBuildRunnerTest`, `ArtifactKeysTest`, plus two new `FileBuildResultRepositoryTest` cases).
Deviations and decisions: 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`. 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. - 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. 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. - 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`. - 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. - 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. - `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). - 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"). - 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). 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. Reuse keeps incremental build caches; `cleanCommand` decides how much of them survives.
`GitService` gained `worktreeAdd`, `worktreePrune`, and `checkoutDetached` for this. `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. - 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. - 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.
docs/plan/05-artifact-store.md
+6 -6
View File
@@ -9,10 +9,10 @@ Persist build artifacts (logs plus configured report directories) with stable na
## Design ## Design
Create package `de.hoennig.gittally.artifacts`: Create package `de.hoennig.werkator.artifacts`:
- `ArtifactStore` service implementing the interface stubbed in step 04. - `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. 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._-]` → `_`. - 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. - 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 ## Config
New key `artifacts.rootDir` (empty = platform default above). 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 ## Tests
@@ -43,11 +43,11 @@ Update `GitTallyConfig`, `InitCommand` templates, and `docs/configuration.md` to
## Execution Notes (done 2026-07-07) ## 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`). (`FileArtifactStoreTest`, `BuildExecutorArtifactIntegrationTest`, plus a `repoKey` case in `ArtifactKeysTest`).
Deviations and decisions: 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. 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)`. - 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. 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. and returns the removed keys.
- `artifactDir` rejects keys outside `[A-Za-z0-9._-]+` and anything resolving outside `<root>/branches/` (path traversal). - `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; - `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`. - The bean is wired in `ArtifactsConfiguration` with the working directory defaulting to `.`, mirroring `BuildConfiguration`.
docs/plan/06-watcher.md
+6 -6
View File
@@ -9,7 +9,7 @@ Replace the legacy blocking main loop with a non-blocking, observable scheduler.
## Design ## 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). - `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: - 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). 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. 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. 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. - 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. - 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. - 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 ## Config
New key `watcher.pollInterval` (e.g. `10s`, default matching legacy cadence). 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 ## Tests
@@ -51,7 +51,7 @@ Update `GitTallyConfig`, `InitCommand` templates, and `docs/configuration.md` to
## Execution Notes (done 2026-07-07) ## 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). (`WatcherTest`, `AutoBuildStateTest`, plus new `DurationParserTest` and `GitServiceTest` cases).
Deviations and decisions: 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; - 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 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). 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 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 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. (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). 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, A stale latest PENDING entry is marked INTERRUPTED before its replacement build is enqueued,
because the executor queue does not survive a restart. 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`. (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`). - `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, - Watcher health is exposed via `Watcher.state(): WatcherState` (running, last poll time, last fetch/poll error,
docs/plan/07-server-mode.md
+3 -3
View File
@@ -18,7 +18,7 @@ Bootstrapping:
- The watcher (step 06) is active only in the `server` profile. - 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). - 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/latest` — latest build per branch.
- `GET /api/builds/history` — all builds, newest first. - `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: 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 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. - `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`. - `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=…`.) - `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). - 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. - 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. `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. SIGINT (Ctrl-C) shut the process down cleanly in about 2 seconds: port closed, no exceptions in the log, exit code 130.
docs/plan/08-web-ui.md
+5 -5
View File
@@ -48,7 +48,7 @@ Robust live updates (the actual bug fix):
## Implementation Notes (2026-07-07) ## 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. 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. 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`. 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. - 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. - 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). - 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. - 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. - `/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). - 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. - 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. - 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. 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). 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. 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. 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. 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. 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. 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.
docs/plan/09-system-metrics.md
+4 -4
View File
@@ -9,7 +9,7 @@ Port the legacy system page: CPU, RAM, disk, and repository size with min/max/av
## Design ## Design
Create package `de.hoennig.gittally.metrics`: Create package `de.hoennig.werkator.metrics`:
- `SystemMetricsCollector` sampling every 60s (server profile only): - `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). 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) ## 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. 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. `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: 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 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. 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. - 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 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`. - The CPU count comes from `Runtime.availableProcessors()` instead of `nproc`.
docs/plan/10-cli-commands.md
+2 -2
View File
@@ -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) ## 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). 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. - `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. - 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. - `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. - 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). 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): Manual smoke test (2026-07-07, in this repository):
docs/plan/11-docker-build-runtime.md
+10 -10
View File
@@ -14,18 +14,18 @@ Implement a `DockerBuildRunner` for the `BuildRunner` interface from step 04, sh
Port from legacy (see analysis, lines ~4400+): 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`). - 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 (`gittally-gradle-<repo-key>`), mounted and chowned to the host UID/GID. - 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. - 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`). - 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). 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 ## Config
New `branches.<name>.docker` section: `enabled`, `image`, `dockerfile`, `context`, `network`, `env`. 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 ## Tests
@@ -46,19 +46,19 @@ No test needs Docker; the main `docker run` argv is asserted exactly through an
Ported from legacy: 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. 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. - 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`). - 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: 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 `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`. - 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. - 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. - 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. - 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. - 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): 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`). - 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. - 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. - 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.
docs/plan/12-deployment.md
+11 -11
View File
@@ -5,13 +5,13 @@ Read `README.md` and `00-legacy-analysis.md` first.
## Goal ## 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 ## Design
Deployment (documentation plus a small generator, no self-install): 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). - 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: Migration:
@@ -21,8 +21,8 @@ Migration:
Housekeeping: Housekeeping:
- Mark `legacy/gitTally` as deprecated in its header comment and in `README.md`. - Mark `legacy/werkator` as deprecated in its header comment and in `README.md`.
- Review `docs/GitTally-Konzept.md` against what was actually built; update or note deviations. - 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). - Add an ADR summarizing the architecture decisions that emerged during the rewrite (persistence choice, polling UI, no nginx management).
## Tests ## Tests
@@ -37,25 +37,25 @@ Housekeeping:
## Implementation Notes (2026-07-07) ## 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. `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.
Deviations and decisions: 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. - `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. 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`. - 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 `gittally.env` is kept; the unit file is regenerated on every run (same as legacy). 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. - 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). - 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). - 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`): 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. - 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. - 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. - 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.
docs/plan/13-nginx-tls.md
+9 -9
View File
@@ -2,22 +2,22 @@
Prerequisites: steps 07, 11, 12. Prerequisites: steps 07, 11, 12.
Read `README.md`, `00-legacy-analysis.md`, and ADR 0005 first. 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 ## Goal
Serve GitTally over HTTPS on hosts that provide Docker but no host reverse proxy (e.g. Hostsharing managed container environments). Serve werkator 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. 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). This is opt-in; the reverse-proxy deployment from step 12 stays the default (ADR 0005).
## Design ## 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): 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`. - 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 (`GitTallyConfig`, `init` templates, `docs/configuration.md`). 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). - 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. - 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. 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. - 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,9 +36,9 @@ Port the legacy nginx subsystem (functions `configure_artifact_nginx_defaults` ~
- `./gradlew ktlintFormat` then `./gradlew build` is green. - `./gradlew ktlintFormat` then `./gradlew build` is green.
- With `server.nginx.enabled: false` (default) nothing changes; no container is touched. - 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. 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. - `docs/deployment.md` gains a section for hosts without a reverse proxy; `docs/migration-from-legacy.md` maps the `werkator_ARTIFACT_NGINX_*`/`werkator_ARTIFACT_LETSENCRYPT_EMAIL` variables.
## Result (2026-07-08) ## Result (2026-07-08)
@@ -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 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). - 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. - `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. - 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). - `ssl-dhparams.pem` is downloaded via the Java HTTP client instead of `curl` (replaceable seam for tests).
docs/plan/14-build-phase-timing-and-overhead.md
+1 -1
View File
@@ -1,7 +1,7 @@
# Step 14: Build-Phase Timing and Orchestration Overhead # Step 14: Build-Phase Timing and Orchestration Overhead
Prerequisites: steps 04 (build executor), 05 (artifact store), 07 (API), 08 (web UI), 11 (Docker runtime). 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/werkator` functions only where this step points at them.
## Goal ## Goal
docs/plan/15-runtime-bundle-distribution.md
+57 -57
View File
@@ -6,8 +6,8 @@ This step revises the "Future: Docker-based Deployment" section of `docs/bootstr
## Goal ## Goal
Deploy GitTally on hosts that provide Docker and git but no Java runtime (Hostsharing container servers, e.g. `tallyman@vm4006`). Deploy werkator 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. 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. The JAR stays the primary artifact for development and for hosts that already have a JRE.
## Distribution Format Decision (ADR 0006) ## 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`. - **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. 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. - **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. 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. Kept as the documented fallback if the bundle approach ever becomes unworkable.
## Target Host Facts (verified 2026-08-10) ## 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. - 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 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. - 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" "$@"`). - 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/gittally-runtime-linux-x64.tar.gz` with preserved execute permissions. - Output: `build/distributions/werkator-runtime-linux-x64.tar.gz` with preserved execute permissions.
Deployment (no code changes expected): Deployment (no code changes expected):
- Unpack to `~/opt/gittally/` on the target host; run everything via `~/opt/gittally/bin/gittally`. - 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/gittally/`, so the unit points at the bundle without changes. - `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. 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: Documentation:
@@ -55,13 +55,13 @@ Documentation:
## Tests ## Tests
- No production code changes are expected, so no new unit tests; existing tests must stay green. - 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. - 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/gittally --help` and `config:print`; 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 ## Acceptance Criteria
- `./gradlew ktlintFormat` then `./gradlew build` is green, with unchanged toolchain requirements. - `./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). - 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. - 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. - 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. 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). 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. - 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. - 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/gittally`, `--version`, `--help`, and `status` in a scratch repo (host git via `GitCommandRunner`) all worked. - 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): 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). - `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: GitTally@vm4006` for the parallel phase; rename to `GitTally` after vm2176 is retired. - `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. - 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). - 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. - Fix discovered during rollout: certbot removed `ssl-dhparams.pem` from its repository, so the first nginx start failed with HTTP 404.
@@ -99,83 +99,83 @@ 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. 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. 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". 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".
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. 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). 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. 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. 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 (`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). 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).
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. 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/`. 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. 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/gittally/.gittally.yml` — which the managed nginx container needs. 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/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. 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. 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. 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 `gittally-control-token`, `/api/builds/latest` and `/branches` still answer 200 without any credential, and a mutation without the token is rejected with 403. 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/gittally/control-token` once per browser now. 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. 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/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. 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. 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. 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/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`). 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. 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. 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/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. 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. 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`). 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/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. 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. 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. 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/gittally --version` reports v0.9.15 before the start, the service is `active`, the API answers, and the watcher polls without errors. 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. 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. 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). 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. 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. 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. 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. 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. 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/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. 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 GitTally it is written for (`gitTally.version.since`/`below`), so an incompatibility is named instead of silently ignored. 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. 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. 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. 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 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. 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`. 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. 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. 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. 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 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. 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. 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 `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). 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).
docs/plan/16-git-in-docker-builds.md
+7 -7
View File
@@ -6,14 +6,14 @@ Motivated by the vm4006 rollout (step 15, fourth finding): hs.hsadmin.ng's build
## Problem ## 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. 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). 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 ## 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. - 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. - 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`): `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. 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. 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. 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 ## Tests
@@ -35,10 +35,10 @@ Remaining, documented exposure: the rest of `.git` — including `.git/config`
## Acceptance Criteria ## Acceptance Criteria
- `./gradlew ktlintFormat` then `./gradlew build` is green. - `./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. - `docs/configuration.md` (docker notes) and the architecture skill describe the mounts.
## Result (2026-08-10) ## Result (2026-08-10)
Implemented as designed; verified on vm4006 (see below) and in unit tests. 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.
docs/plan/17-bwrap-build-runtime.md
+17 -17
View File
@@ -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. Prerequisites: steps 11, 15, 16.
Read `README.md` first. 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. 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: GitTally builds GitTally itself on a Managed Webspace; builds needing special dependencies get them from a prepared root filesystem instead of the host. 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. 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 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). 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) ## 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. **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. 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. 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 ## Goal
@@ -58,8 +58,8 @@ No root on the host, no Docker daemon, no changes to the native and Docker runti
### Prepared root filesystem ### Prepared root filesystem
`debootstrap`/`mmdebstrap` are not available on the webspace, so the rootfs is **not created on the target system**. `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). 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).
GitTally unpacks it on demand (`tar --no-same-owner`) into `.git/gittally/buildenv/<envKey>/rootfs` — **not** into the working tree. 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. 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 ### 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`). 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. `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. `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 ### Invocation
@@ -84,7 +84,7 @@ bwrap --unshare-user --unshare-pid --die-with-parent --uid 0 --gid 0 \
/bin/sh -c '<buildCommand>' /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. - `<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. - `--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. - 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. - 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. - 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) ## 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. 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. 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/). 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`). 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). 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. 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/). Source: [TLS](https://www.hostsharing.net/doc/managed-operations-platform/tls/).
### User model: a dedicated unix user, not the package admin ### 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. 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. 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/). 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). 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 ```yaml
server: server:
@@ -148,7 +148,7 @@ server:
enabled: false # the managed nginx container is not used on a webspace 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: 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. - 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). - `./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. - 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. - 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.
docs/plan/18-remove-branches-section.md
+10 -10
View File
@@ -11,12 +11,12 @@ The `trigger` block, originally planned here, shipped earlier — see the sectio
## Precondition Check (run first, do not skip) ## 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: So no configuration still in play may contain the section. On vm4006:
```bash ```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. 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; 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 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. 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. 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 ## 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. 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()`. `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. 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. 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. - `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". - `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. 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 ## Already done: the `trigger` block
@@ -75,13 +75,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. 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. 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. 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. 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. 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`). 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. 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. `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 +94,12 @@ Deploy as usual (`docs/plan/15-runtime-bundle-distribution.md`), only while `/ap
## Verification ## 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. 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`. - 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. - 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 ## 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. 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.
docs/plan/19-watcher-health-in-ui.md
+3 -3
View File
@@ -6,7 +6,7 @@ Read `README.md` first.
## Why ## Why
On 2026-08-30 the Gitea token in the machine config on vm4006 was replaced by a placeholder string. 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 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. 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 ## 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. 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. - `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>`. - 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. - 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. This banner reports whether the *server* reaches origin. Two independent failures, two independent signals.
docs/plan/README.md
+9 -9
View File
@@ -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 `legacy/werkator` (bash) as the Kotlin/Spring application in this repository.
Each step file is self-contained and sized for one focused Claude Code session. Each step file is self-contained and sized for one focused Claude Code session.
## How to Execute a Step ## How to Execute a Step
@@ -9,7 +9,7 @@ Start a fresh Claude Code session and prompt, for example: "Execute docs/plan/01
The executing session should: The executing session should:
1. Read this file, `00-legacy-analysis.md`, and the step file. 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 `legacy/werkator` only if the step file says so.
3. Implement with tests, following `CLAUDE.md` conventions. 3. Implement with tests, following `CLAUDE.md` conventions.
4. Run `./gradlew ktlintFormat` and then `./gradlew build` until green. 4. Run `./gradlew ktlintFormat` and then `./gradlew build` until green.
5. Update the step's checkbox below and note deviations inside the step file. 5. Update the step's checkbox below and note deviations inside the step file.
@@ -22,16 +22,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). - 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`). - 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. - 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 ## Proposed Architecture Decisions
These are proposals baked into the steps. These are proposals baked into the steps.
Revisit them in an ADR if a step uncovers problems. 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. - 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. 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. - Artifacts stay on the filesystem, served by the Spring server.
- The web UI is server-rendered HTML plus small JavaScript polling JSON endpoints (no SPA framework). - The web UI is server-rendered HTML plus small JavaScript polling JSON endpoints (no SPA framework).
@@ -76,7 +76,7 @@ Added after the 2026-08-10 overhead measurements on vm2176:
Added for the vm2176 → vm4006 migration (2026-08-10): 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] `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): Added after v0.9.19 replaced the per-branch settings with build definitions (2026-08-29):
@@ -86,9 +86,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 - [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 01–03 are independent of each other.
Steps 04–06 depend on 01–03. Steps 04–06 depend on 01–03.
legacy/.gitTally
-176
View File
@@ -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'
legacy/gitTally
-5970
View File
File diff suppressed because it is too large Load Diff
packaging/gittally
+2 -2
View File
@@ -1,6 +1,6 @@
#!/bin/sh #!/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. # Built by `./gradlew runtimeBundle`; see docs/deployment.md.
DIR=$(CDPATH='' cd -- "$(dirname -- "$(readlink -f -- "$0")")" && pwd) DIR=$(CDPATH='' cd -- "$(dirname -- "$(readlink -f -- "$0")")" && pwd)
# shellcheck disable=SC2086 # JAVA_OPTS is intentionally word-split # 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" "$@"
settings.gradle.kts
+1 -1
View File
@@ -1 +1 @@
rootProject.name = "gittally" rootProject.name = "werkator"
src/main/kotlin/de/hoennig/gittally/SecretFiles.kt
+2 -2
View File
@@ -1,4 +1,4 @@
package de.hoennig.gittally package de.hoennig.werkator
import java.nio.ByteBuffer import java.nio.ByteBuffer
import java.nio.file.Files 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 * 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: * 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 * writing at the umask default first (typically `0644`) would leave a window in
src/main/kotlin/de/hoennig/gittally/GitTallyApplication.kt → src/main/kotlin/de/hoennig/gittally/WerkatorApplication.kt
+6 -6
View File
@@ -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.CommandLineRunner
import org.springframework.boot.ExitCodeGenerator import org.springframework.boot.ExitCodeGenerator
import org.springframework.boot.SpringApplication import org.springframework.boot.SpringApplication
@@ -13,14 +13,14 @@ import picocli.CommandLine.IFactory
import kotlin.system.exitProcess import kotlin.system.exitProcess
@SpringBootApplication @SpringBootApplication
class GitTallyApplication class WerkatorApplication
/** Not in the `server` profile: the second context started by `ServerCommand` must not run picocli again. */ /** Not in the `server` profile: the second context started by `ServerCommand` must not run picocli again. */
@Component @Component
@Profile("!server") @Profile("!server")
class CliRunner( class CliRunner(
private val factory: IFactory, private val factory: IFactory,
private val rootCommand: GitTallyCommand, private val rootCommand: werkatorCommand,
) : CommandLineRunner, ) : CommandLineRunner,
ExitCodeGenerator { ExitCodeGenerator {
private var exitCode = 0 private var exitCode = 0
@@ -29,7 +29,7 @@ class CliRunner(
exitCode = exitCode =
CommandLine(rootCommand, factory) CommandLine(rootCommand, factory)
.setExecutionExceptionHandler { exception, commandLine, _ -> .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 // names the file, the versions, and the way out — a stack trace would bury it
if (exception is ConfigException) { if (exception is ConfigException) {
commandLine.err.println("Error: ${exception.message}") commandLine.err.println("Error: ${exception.message}")
@@ -49,5 +49,5 @@ class CliRunner(
} }
fun main(args: Array<String>) { fun main(args: Array<String>) {
exitProcess(SpringApplication.exit(runApplication<GitTallyApplication>(*args))) exitProcess(SpringApplication.exit(runApplication<WerkatorApplication>(*args)))
} }
src/main/kotlin/de/hoennig/gittally/GitTallyCommand.kt → src/main/kotlin/de/hoennig/gittally/WerkatorCommand.kt
+10 -10
View File
@@ -1,11 +1,11 @@
package de.hoennig.gittally package de.hoennig.werkator
import de.hoennig.gittally.commands.BuildCommand import de.hoennig.werkator.commands.BuildCommand
import de.hoennig.gittally.commands.ConfigPrintCommand import de.hoennig.werkator.commands.ConfigPrintCommand
import de.hoennig.gittally.commands.InitCommand import de.hoennig.werkator.commands.InitCommand
import de.hoennig.gittally.commands.RetryCommand import de.hoennig.werkator.commands.RetryCommand
import de.hoennig.gittally.commands.ServerCommand import de.hoennig.werkator.commands.ServerCommand
import de.hoennig.gittally.commands.StatusCommand import de.hoennig.werkator.commands.StatusCommand
import org.springframework.beans.factory.ObjectProvider import org.springframework.beans.factory.ObjectProvider
import org.springframework.boot.info.BuildProperties import org.springframework.boot.info.BuildProperties
import org.springframework.stereotype.Component import org.springframework.stereotype.Component
@@ -14,7 +14,7 @@ import picocli.CommandLine.Command
@Component @Component
@Command( @Command(
name = "gittally", name = "werkator",
subcommands = [ subcommands = [
InitCommand::class, InitCommand::class,
ServerCommand::class, ServerCommand::class,
@@ -27,7 +27,7 @@ import picocli.CommandLine.Command
versionProvider = BuildPropertiesVersionProvider::class, versionProvider = BuildPropertiesVersionProvider::class,
description = ["Lightweight, declarative CI/CD system"], description = ["Lightweight, declarative CI/CD system"],
) )
class GitTallyCommand : Runnable { class werkatorCommand : Runnable {
override fun run(): Unit = throw CommandLine.ParameterException(CommandLine(this), "Specify a subcommand") override fun run(): Unit = throw CommandLine.ParameterException(CommandLine(this), "Specify a subcommand")
} }
@@ -41,5 +41,5 @@ class GitTallyCommand : Runnable {
class BuildPropertiesVersionProvider( class BuildPropertiesVersionProvider(
private val buildProperties: ObjectProvider<BuildProperties>, private val buildProperties: ObjectProvider<BuildProperties>,
) : CommandLine.IVersionProvider { ) : 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"}")
} }
src/main/kotlin/de/hoennig/gittally/artifacts/ArtifactsConfiguration.kt
+3 -3
View File
@@ -1,7 +1,7 @@
package de.hoennig.gittally.artifacts package de.hoennig.werkator.artifacts
import de.hoennig.gittally.build.ArtifactStore import de.hoennig.werkator.build.ArtifactStore
import de.hoennig.gittally.config.ConfigLoader import de.hoennig.werkator.config.ConfigLoader
import org.springframework.context.annotation.Bean import org.springframework.context.annotation.Bean
import org.springframework.context.annotation.Configuration import org.springframework.context.annotation.Configuration
src/main/kotlin/de/hoennig/gittally/artifacts/FileArtifactStore.kt
+10 -10
View File
@@ -1,10 +1,10 @@
package de.hoennig.gittally.artifacts package de.hoennig.werkator.artifacts
import de.hoennig.gittally.build.ArtifactKeys import de.hoennig.werkator.build.ArtifactKeys
import de.hoennig.gittally.build.ArtifactStore import de.hoennig.werkator.build.ArtifactStore
import de.hoennig.gittally.build.BuildResult import de.hoennig.werkator.build.BuildResult
import de.hoennig.gittally.config.BranchConfig import de.hoennig.werkator.config.BranchConfig
import de.hoennig.gittally.config.ConfigLoader import de.hoennig.werkator.config.ConfigLoader
import org.slf4j.LoggerFactory import org.slf4j.LoggerFactory
import java.io.IOException import java.io.IOException
import java.nio.file.FileVisitResult import java.nio.file.FileVisitResult
@@ -22,7 +22,7 @@ import kotlin.concurrent.write
/** /**
* Stores build artifacts on the filesystem under `<root>/branches/<artifactKey>/`. * Stores build artifacts on the filesystem under `<root>/branches/<artifactKey>/`.
* The root is `artifacts.rootDir` from the config, or the platform default * 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. * deliberately not `/tmp` like legacy, where artifacts vanished on reboot.
* *
* Each build is assembled in a temporary directory next to its target and moved * 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) } env("XDG_STATE_HOME")?.takeIf { it.isNotBlank() }?.let { Paths.get(it) }
?: Paths.get(System.getProperty("user.home"), ".local", "state") ?: Paths.get(System.getProperty("user.home"), ".local", "state")
return stateHome return stateHome
.resolve("gittally") .resolve("werkator")
.resolve("artifacts") .resolve("artifacts")
.resolve(ArtifactKeys.repoKey(workingDir)) .resolve(ArtifactKeys.repoKey(workingDir))
.toAbsolutePath() .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 * 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. * only the ones its branch would have used.
*/ */
private fun buildSettings( private fun buildSettings(
src/main/kotlin/de/hoennig/gittally/build/ArtifactKeys.kt
+1 -1
View File
@@ -1,4 +1,4 @@
package de.hoennig.gittally.build package de.hoennig.werkator.build
import java.nio.file.Path import java.nio.file.Path
import java.security.MessageDigest import java.security.MessageDigest
src/main/kotlin/de/hoennig/gittally/build/ArtifactStore.kt
+2 -2
View File
@@ -1,11 +1,11 @@
package de.hoennig.gittally.build package de.hoennig.werkator.build
import java.nio.file.Path import java.nio.file.Path
/** /**
* Persists the artifacts of finished builds (logs plus configured report directories) * Persists the artifacts of finished builds (logs plus configured report directories)
* and prunes them together with the result retention. * and prunes them together with the result retention.
* Implemented by `de.hoennig.gittally.artifacts.FileArtifactStore`. * Implemented by `de.hoennig.werkator.artifacts.FileArtifactStore`.
*/ */
interface ArtifactStore { interface ArtifactStore {
/** /**
src/main/kotlin/de/hoennig/gittally/build/BranchWorkspaces.kt
+4 -4
View File
@@ -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.slf4j.LoggerFactory
import org.springframework.stereotype.Component import org.springframework.stereotype.Component
import java.nio.file.Files 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 * checked out detached at the requested commit. Reuse keeps incremental build
* caches; the branch's `cleanCommand` decides how much of them survives. * caches; the branch's `cleanCommand` decides how much of them survives.
*/ */
@@ -50,6 +50,6 @@ class GitWorktreeWorkspaces(
} }
companion object { companion object {
const val WORKTREES_DIR = ".git/gittally/worktrees" const val WORKTREES_DIR = ".git/werkator/worktrees"
} }
} }
src/main/kotlin/de/hoennig/gittally/build/BuildConfiguration.kt
+3 -3
View File
@@ -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.Bean
import org.springframework.context.annotation.Configuration import org.springframework.context.annotation.Configuration
@@ -8,9 +8,9 @@ import java.nio.file.Paths
class BuildConfiguration { class BuildConfiguration {
/** /**
* Results file relative to the working directory, matching how `ConfigLoader` * 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. * first build runs, so the bean is safe outside a git repository.
*/ */
@Bean @Bean
fun buildResultRepository(): BuildResultRepository = FileBuildResultRepository(Paths.get(".git/gittally/build-results.json")) fun buildResultRepository(): BuildResultRepository = FileBuildResultRepository(Paths.get(".git/werkator/build-results.json"))
} }
src/main/kotlin/de/hoennig/gittally/build/BuildExecutor.kt
+9 -9
View File
@@ -1,9 +1,9 @@
package de.hoennig.gittally.build package de.hoennig.werkator.build
import de.hoennig.gittally.config.BranchConfig import de.hoennig.werkator.config.BranchConfig
import de.hoennig.gittally.config.BuildDefinition import de.hoennig.werkator.config.BuildDefinition
import de.hoennig.gittally.config.ConfigLoader import de.hoennig.werkator.config.ConfigLoader
import de.hoennig.gittally.gitea.GiteaClient import de.hoennig.werkator.gitea.GiteaClient
import org.slf4j.LoggerFactory import org.slf4j.LoggerFactory
import org.springframework.context.ApplicationEventPublisher import org.springframework.context.ApplicationEventPublisher
import org.springframework.context.event.ContextClosedEvent import org.springframework.context.event.ContextClosedEvent
@@ -93,7 +93,7 @@ class BuildExecutor(
return duplicate.runningBuild return duplicate.runningBuild
} }
val startedAt = Instant.now() val startedAt = Instant.now()
val stagingDir = Files.createTempDirectory("gittally-build-") val stagingDir = Files.createTempDirectory("werkator-build-")
val runningBuild = val runningBuild =
RunningBuild( RunningBuild(
branch = branch, branch = branch,
@@ -249,7 +249,7 @@ class BuildExecutor(
private fun serialWorker(branch: String): ExecutorService = private fun serialWorker(branch: String): ExecutorService =
Executors.newSingleThreadExecutor { runnable -> 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( private fun runBuildCommands(
@@ -324,7 +324,7 @@ class BuildExecutor(
input: InputStream, input: InputStream,
vararg sinks: OutputStream, vararg sinks: OutputStream,
): Thread = ): Thread =
thread(isDaemon = true, name = "gittally-build-log") { thread(isDaemon = true, name = "werkator-build-log") {
val buffer = ByteArray(8192) val buffer = ByteArray(8192)
try { try {
while (true) { while (true) {
@@ -480,7 +480,7 @@ class BuildExecutor(
/** /**
* The effective settings of this run: the branch config with the build [worktree]'s * 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 * 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 * 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. * (a stale result whose job was removed) falls back to the plain branch settings.
src/main/kotlin/de/hoennig/gittally/build/BuildResult.kt
+2 -2
View File
@@ -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.Duration
import java.time.Instant import java.time.Instant
src/main/kotlin/de/hoennig/gittally/build/BuildResultRepository.kt
+1 -1
View File
@@ -1,4 +1,4 @@
package de.hoennig.gittally.build package de.hoennig.werkator.build
import java.time.Instant import java.time.Instant
src/main/kotlin/de/hoennig/gittally/build/BuildRunner.kt
+2 -2
View File
@@ -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.context.annotation.Primary
import org.springframework.stereotype.Component import org.springframework.stereotype.Component
import java.nio.file.Path import java.nio.file.Path
src/main/kotlin/de/hoennig/gittally/build/BuildStatus.kt
+1 -1
View File
@@ -1,4 +1,4 @@
package de.hoennig.gittally.build package de.hoennig.werkator.build
enum class BuildStatus { enum class BuildStatus {
PENDING, PENDING,
src/main/kotlin/de/hoennig/gittally/build/DockerBuildRunner.kt
+23 -23
View File
@@ -1,8 +1,8 @@
package de.hoennig.gittally.build package de.hoennig.werkator.build
import de.hoennig.gittally.config.BranchConfig import de.hoennig.werkator.config.BranchConfig
import de.hoennig.gittally.config.DockerConfig import de.hoennig.werkator.config.DockerConfig
import de.hoennig.gittally.git.GitCommandRunner import de.hoennig.werkator.git.GitCommandRunner
import org.slf4j.LoggerFactory import org.slf4j.LoggerFactory
import org.springframework.stereotype.Component import org.springframework.stereotype.Component
import java.nio.file.Files 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 * 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`. * 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 works inside the container: the primary `.git` is mounted read-only with
* `.git/gittally/` masked, see [gitMetadataMounts]. * `.git/werkator/` masked, see [gitMetadataMounts].
*/ */
@Component @Component
class DockerBuildRunner( class DockerBuildRunner(
@@ -114,11 +114,11 @@ class DockerBuildRunner(
"docker", "docker",
"build", "build",
"--label", "--label",
"org.gittally.dockerfile=${docker.dockerfile}", "org.werkator.dockerfile=${docker.dockerfile}",
"--label", "--label",
"org.gittally.dockerfile-sha256=$dockerfileHash", "org.werkator.dockerfile-sha256=$dockerfileHash",
"--label", "--label",
"org.gittally.build-context=${docker.context}", "org.werkator.build-context=${docker.context}",
"--label", "--label",
"${DockerImageInputs.INPUTS_LABEL}=$inputsHash", "${DockerImageInputs.INPUTS_LABEL}=$inputsHash",
"-t", "-t",
@@ -194,11 +194,11 @@ class DockerBuildRunner(
"ps", "ps",
"-aq", "-aq",
"--filter", "--filter",
"label=$GITTALLY_LABEL=true", "label=$werkator_LABEL=true",
"--filter", "--filter",
"label=$GITTALLY_LABEL.repository=$repoKey", "label=$werkator_LABEL.repository=$repoKey",
"--filter", "--filter",
"label=$GITTALLY_LABEL.role=build", "label=$werkator_LABEL.role=build",
), ),
repoDir, repoDir,
) )
@@ -238,11 +238,11 @@ class DockerBuildRunner(
args += args +=
listOf( listOf(
"--label", "--label",
"$GITTALLY_LABEL=true", "$werkator_LABEL=true",
"--label", "--label",
"$GITTALLY_LABEL.repository=$repoKey", "$werkator_LABEL.repository=$repoKey",
"--label", "--label",
"$GITTALLY_LABEL.role=build", "$werkator_LABEL.role=build",
) )
args += listOf("--workdir", "$workspace", "--volume", "$workspace:$workspace") args += listOf("--workdir", "$workspace", "--volume", "$workspace:$workspace")
args += gitMetadataMounts(workspace, repoDir) 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 * 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 * 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 * 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 * (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 * 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. * directory read-write, so index-refreshing commands like `git status` keep working.
@@ -312,9 +312,9 @@ class DockerBuildRunner(
return emptyList() return emptyList()
} }
val args = mutableListOf("--volume", "$gitDir:$gitDir:ro") val args = mutableListOf("--volume", "$gitDir:$gitDir:ro")
val gittallyDir = gitDir.resolve("gittally") val werkatorDir = gitDir.resolve("werkator")
if (Files.isDirectory(gittallyDir)) { if (Files.isDirectory(werkatorDir)) {
args += listOf("--tmpfs", "$gittallyDir") args += listOf("--tmpfs", "$werkatorDir")
} }
args += listOf("--volume", "$adminDir:$adminDir") args += listOf("--volume", "$adminDir:$adminDir")
return args return args
@@ -326,15 +326,15 @@ class DockerBuildRunner(
): String = commandRunner.runOrThrow(listOf("id", flag), repoDir).stdout.trim() ): String = commandRunner.runOrThrow(listOf("id", flag), repoDir).stdout.trim()
companion object { companion object {
/** Container label namespace; legacy used `org.hostsharing.gittally`. */ /** Container label namespace; legacy used `org.hostsharing.werkator`. */
const val GITTALLY_LABEL = "org.hoennig.gittally" 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( fun containerName(
repoKey: String, repoKey: String,
branch: 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}" }}""" private val INSPECT_INPUTS_LABEL_FORMAT = """{{ index .Config.Labels "${DockerImageInputs.INPUTS_LABEL}" }}"""
src/main/kotlin/de/hoennig/gittally/build/DockerImageInputs.kt
+2 -2
View File
@@ -1,4 +1,4 @@
package de.hoennig.gittally.build package de.hoennig.werkator.build
import java.nio.file.Files import java.nio.file.Files
import java.nio.file.Path 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. * with the configured Dockerfile and context paths, stored as an image label.
*/ */
object DockerImageInputs { 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)) fun dockerfileSha256(dockerfile: Path): String = sha256Hex(Files.readAllBytes(dockerfile))
src/main/kotlin/de/hoennig/gittally/build/DockerSocketLocator.kt
+1 -1
View File
@@ -1,4 +1,4 @@
package de.hoennig.gittally.build package de.hoennig.werkator.build
import org.springframework.stereotype.Component import org.springframework.stereotype.Component
import java.nio.file.Files import java.nio.file.Files
src/main/kotlin/de/hoennig/gittally/build/FileBuildResultRepository.kt
+2 -2
View File
@@ -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.DeserializationFeature
import com.fasterxml.jackson.databind.ObjectMapper import com.fasterxml.jackson.databind.ObjectMapper
@@ -13,7 +13,7 @@ import java.nio.file.StandardCopyOption
import java.time.Instant 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. * Writes are atomic (temp file + atomic move) so readers never see partial content.
*/ */
class FileBuildResultRepository( class FileBuildResultRepository(
src/main/kotlin/de/hoennig/gittally/build/RunningBuild.kt
+2 -2
View File
@@ -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.nio.file.Path
import java.time.Instant import java.time.Instant
src/main/kotlin/de/hoennig/gittally/commands/BranchNameResolution.kt
+1 -1
View File
@@ -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 * Port of the legacy `resolve_branch_name` partial-name matching: a branch-name
src/main/kotlin/de/hoennig/gittally/commands/BuildCommand.kt
+3 -3
View File
@@ -1,7 +1,7 @@
package de.hoennig.gittally.commands package de.hoennig.werkator.commands
import de.hoennig.gittally.build.BuildStatus import de.hoennig.werkator.build.BuildStatus
import de.hoennig.gittally.git.GitService import de.hoennig.werkator.git.GitService
import org.springframework.stereotype.Component import org.springframework.stereotype.Component
import picocli.CommandLine.Command import picocli.CommandLine.Command
import picocli.CommandLine.ExitCode import picocli.CommandLine.ExitCode
src/main/kotlin/de/hoennig/gittally/commands/ConfigPrintCommand.kt
+2 -2
View File
@@ -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 org.springframework.stereotype.Component
import picocli.CommandLine.Command import picocli.CommandLine.Command
import picocli.CommandLine.Option import picocli.CommandLine.Option
src/main/kotlin/de/hoennig/gittally/commands/ConsoleBuildRunner.kt
+9 -9
View File
@@ -1,13 +1,13 @@
package de.hoennig.gittally.commands package de.hoennig.werkator.commands
import de.hoennig.gittally.build.ArtifactStore import de.hoennig.werkator.build.ArtifactStore
import de.hoennig.gittally.build.BuildExecutor import de.hoennig.werkator.build.BuildExecutor
import de.hoennig.gittally.build.BuildResult import de.hoennig.werkator.build.BuildResult
import de.hoennig.gittally.build.BuildResultRepository import de.hoennig.werkator.build.BuildResultRepository
import de.hoennig.gittally.build.BuildStatus import de.hoennig.werkator.build.BuildStatus
import de.hoennig.gittally.build.RunningBuild import de.hoennig.werkator.build.RunningBuild
import de.hoennig.gittally.config.BuildDefinition import de.hoennig.werkator.config.BuildDefinition
import de.hoennig.gittally.server.UiFormats import de.hoennig.werkator.server.UiFormats
import org.springframework.stereotype.Component import org.springframework.stereotype.Component
import java.io.IOException import java.io.IOException
import java.nio.channels.Channels import java.nio.channels.Channels
src/main/kotlin/de/hoennig/gittally/commands/InitCommand.kt
+30 -30
View File
@@ -1,7 +1,7 @@
package de.hoennig.gittally.commands package de.hoennig.werkator.commands
import de.hoennig.gittally.SecretFiles import de.hoennig.werkator.SecretFiles
import de.hoennig.gittally.git.GitService import de.hoennig.werkator.git.GitService
import org.springframework.beans.factory.ObjectProvider import org.springframework.beans.factory.ObjectProvider
import org.springframework.boot.info.BuildProperties import org.springframework.boot.info.BuildProperties
import org.springframework.stereotype.Component import org.springframework.stereotype.Component
@@ -13,19 +13,19 @@ import java.nio.file.Paths
@Component @Component
@Command( @Command(
name = "init", name = "init",
description = ["Initialize GitTally for the current repository"], description = ["Initialize werkator for the current repository"],
mixinStandardHelpOptions = true, mixinStandardHelpOptions = true,
) )
class InitCommand( class InitCommand(
private val gitService: GitService, 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, private val buildProperties: ObjectProvider<BuildProperties>? = null,
) : Runnable { ) : Runnable {
var workingDir: Path = Paths.get(".") var workingDir: Path = Paths.get(".")
@Option( @Option(
names = ["--systemd"], 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 var systemd: Boolean = false
@@ -56,7 +56,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. * 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" private fun runningVersion(): String = buildProperties?.getIfAvailable()?.version ?: "0.0.0"
@@ -99,7 +99,7 @@ class InitCommand(
detected: DetectedValues, detected: DetectedValues,
normalizedWorkingDir: Path, normalizedWorkingDir: Path,
) { ) {
val file = root.resolve(".git/gittally/.gittally.yml") val file = root.resolve(".git/werkator/.werkator.yml")
if (file.toFile().exists()) { if (file.toFile().exists()) {
println("${file.toFile().relativeTo(normalizedWorkingDir.toFile())} already exists — not overwritten") println("${file.toFile().relativeTo(normalizedWorkingDir.toFile())} already exists — not overwritten")
return return
@@ -107,7 +107,7 @@ class InitCommand(
SecretFiles.createDirectoriesOwnerOnly(file.parent) SecretFiles.createDirectoriesOwnerOnly(file.parent)
val content = 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: git:
account: "${detected.account}" # technical username for git HTTPS authentication account: "${detected.account}" # technical username for git HTTPS authentication
token: "" # Gitea API token — never commit this token: "" # Gitea API token — never commit this
@@ -123,31 +123,31 @@ class InitCommand(
detected: DetectedValues, detected: DetectedValues,
normalizedWorkingDir: Path, normalizedWorkingDir: Path,
) { ) {
val file = root.resolve(".gittally.yml") val file = root.resolve(".werkator.yml")
if (file.toFile().exists()) { if (file.toFile().exists()) {
println("${file.toFile().relativeTo(normalizedWorkingDir.toFile())} already exists — not overwritten") println("${file.toFile().relativeTo(normalizedWorkingDir.toFile())} already exists — not overwritten")
return return
} }
val content = val content =
""" """
# The GitTally this file is written for. # The werkator this file is written for.
# since: enforced — an older GitTally refuses to read this file instead of # since: enforced — an older werkator refuses to read this file instead of
# silently ignoring the keys it does not know yet. # 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. # to take it, and warns rather than blocks unless the format really broke.
gitTally: werkator:
version: version:
since: "${runningVersion()}" since: "${runningVersion()}"
# below: "2.0" # below: "2.0"
server: 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: "" publicBaseUrl: ""
# HTTP port of the `server` subcommand # HTTP port of the `server` subcommand
port: 18080 port: 18080
# bind address of the `server` subcommand; loopback only, because the UI and the # 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 # 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 bindAddress: 127.0.0.1
# optional Impressum (legal disclosure) link in the web UI footer; empty hides the link # optional Impressum (legal disclosure) link in the web UI footer; empty hides the link
impressumUrl: "" impressumUrl: ""
@@ -159,8 +159,8 @@ class InitCommand(
httpPort: 8080 # host port published as nginx port 80 httpPort: 8080 # host port published as nginx port 80
httpsPort: 8443 # host port published as nginx port 443 httpsPort: 8443 # host port published as nginx port 443
upstreamHost: "" # host nginx proxies to; empty = serverName upstreamHost: "" # host nginx proxies to; empty = serverName
containerName: "" # empty = gittally-nginx-<repo-name> containerName: "" # empty = werkator-nginx-<repo-name>
stateDir: "" # empty = XDG_STATE_HOME (or ~/.local/state) + /gittally/nginx/<repo-key> 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 letsencryptEmail: "" # e-mail for the Let's Encrypt account; empty registers without one
# Gitea integration for fetching commits and posting build statuses. # Gitea integration for fetching commits and posting build statuses.
@@ -168,7 +168,7 @@ class InitCommand(
baseUrl: ${detected.baseUrl} # base URL of the Gitea instance baseUrl: ${detected.baseUrl} # base URL of the Gitea instance
owner: ${detected.owner} # repository owner (user or organisation) for Gitea API (e.g. status checks) owner: ${detected.owner} # repository owner (user or organisation) for Gitea API (e.g. status checks)
repo: ${detected.repo} # repository name 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. # Build execution settings, enforced for all builds regardless of their trigger.
executor: executor:
@@ -178,7 +178,7 @@ class InitCommand(
# Named build definitions (jobs); every key names a build. # Named build definitions (jobs); every key names a build.
# "default" is the base every other definition inherits its settings from — never # "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. # 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. # they apply to that branch alone, so a new job can be tried out on one branch.
builds: builds:
default: default:
@@ -218,11 +218,11 @@ class InitCommand(
# atTimes: ["01:00"] # atTimes: ["01:00"]
# branches: ["master"] # branches: ["master"]
# buildCommand: ./gradlew pitestFull # buildCommand: ./gradlew pitestFull
# statusContext: GitTally/pitest # statusContext: werkator/pitest
# Build artifact storage and retention. # Build artifact storage and retention.
artifacts: 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: "" rootDir: ""
# number of builds to keep per branch # number of builds to keep per branch
retentionPerBranch: 3 retentionPerBranch: 3
@@ -256,14 +256,14 @@ class InitCommand(
) { ) {
val jarPath = jarPathResolver() val jarPath = jarPathResolver()
if (jarPath == null) { 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 return
} }
val gittallyDir = root.resolve(".git/gittally") val werkatorDir = root.resolve(".git/werkator")
SecretFiles.createDirectoriesOwnerOnly(gittallyDir) SecretFiles.createDirectoriesOwnerOnly(werkatorDir)
val unitName = SystemdServiceFiles.unitName(root) val unitName = SystemdServiceFiles.unitName(root)
val unitFile = gittallyDir.resolve(unitName) val unitFile = werkatorDir.resolve(unitName)
val envFile = gittallyDir.resolve(SystemdServiceFiles.ENV_FILE_NAME) val envFile = werkatorDir.resolve(SystemdServiceFiles.ENV_FILE_NAME)
unitFile.toFile().writeText( unitFile.toFile().writeText(
SystemdServiceFiles.unitFileContent( SystemdServiceFiles.unitFileContent(
@@ -283,9 +283,9 @@ class InitCommand(
} }
// the nightly Docker cleanup is host-global: every repository generates the same // the nightly Docker cleanup is host-global: every repository generates the same
// units, so with several GitTally instances the symlinks simply coincide // units, so with several werkator instances the symlinks simply coincide
val pruneServiceFile = gittallyDir.resolve(SystemdServiceFiles.PRUNE_SERVICE_NAME) val pruneServiceFile = werkatorDir.resolve(SystemdServiceFiles.PRUNE_SERVICE_NAME)
val pruneTimerFile = gittallyDir.resolve(SystemdServiceFiles.PRUNE_TIMER_NAME) val pruneTimerFile = werkatorDir.resolve(SystemdServiceFiles.PRUNE_TIMER_NAME)
pruneServiceFile.toFile().writeText(SystemdServiceFiles.pruneServiceContent()) pruneServiceFile.toFile().writeText(SystemdServiceFiles.pruneServiceContent())
println("created ${pruneServiceFile.toFile().relativeTo(normalizedWorkingDir.toFile())}") println("created ${pruneServiceFile.toFile().relativeTo(normalizedWorkingDir.toFile())}")
pruneTimerFile.toFile().writeText(SystemdServiceFiles.pruneTimerContent()) pruneTimerFile.toFile().writeText(SystemdServiceFiles.pruneTimerContent())
src/main/kotlin/de/hoennig/gittally/commands/RetryCommand.kt
+5 -5
View File
@@ -1,9 +1,9 @@
package de.hoennig.gittally.commands package de.hoennig.werkator.commands
import de.hoennig.gittally.build.BuildResult import de.hoennig.werkator.build.BuildResult
import de.hoennig.gittally.build.BuildResultRepository import de.hoennig.werkator.build.BuildResultRepository
import de.hoennig.gittally.build.BuildStatus import de.hoennig.werkator.build.BuildStatus
import de.hoennig.gittally.git.GitService import de.hoennig.werkator.git.GitService
import org.springframework.stereotype.Component import org.springframework.stereotype.Component
import picocli.CommandLine.Command import picocli.CommandLine.Command
import picocli.CommandLine.ExitCode import picocli.CommandLine.ExitCode
src/main/kotlin/de/hoennig/gittally/commands/ServerCommand.kt
+6 -6
View File
@@ -1,7 +1,7 @@
package de.hoennig.gittally.commands package de.hoennig.werkator.commands
import de.hoennig.gittally.GitTallyApplication import de.hoennig.werkator.WerkatorApplication
import de.hoennig.gittally.config.ConfigLoader import de.hoennig.werkator.config.ConfigLoader
import org.springframework.boot.WebApplicationType import org.springframework.boot.WebApplicationType
import org.springframework.boot.builder.SpringApplicationBuilder import org.springframework.boot.builder.SpringApplicationBuilder
import org.springframework.context.ApplicationListener import org.springframework.context.ApplicationListener
@@ -24,7 +24,7 @@ import java.util.concurrent.CountDownLatch
@Component @Component
@Command( @Command(
name = "server", name = "server",
description = ["Start the GitTally server"], description = ["Start the werkator server"],
mixinStandardHelpOptions = true, mixinStandardHelpOptions = true,
) )
class ServerCommand( class ServerCommand(
@@ -35,7 +35,7 @@ class ServerCommand(
override fun run() { override fun run() {
val config = configLoader.load(workingDir) val config = configLoader.load(workingDir)
val context = val context =
SpringApplicationBuilder(GitTallyApplication::class.java) SpringApplicationBuilder(WerkatorApplication::class.java)
.web(WebApplicationType.SERVLET) .web(WebApplicationType.SERVLET)
.profiles(SERVER_PROFILE) .profiles(SERVER_PROFILE)
.properties( .properties(
@@ -43,7 +43,7 @@ class ServerCommand(
"server.address=${config.server.bindAddress}", "server.address=${config.server.bindAddress}",
).run() ).run()
val port = context.environment.getProperty("local.server.port", config.server.port.toString()) 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) awaitShutdown(context)
} }
src/main/kotlin/de/hoennig/gittally/commands/StatusCommand.kt
+4 -4
View File
@@ -1,8 +1,8 @@
package de.hoennig.gittally.commands package de.hoennig.werkator.commands
import de.hoennig.gittally.build.BuildResult import de.hoennig.werkator.build.BuildResult
import de.hoennig.gittally.build.BuildResultRepository import de.hoennig.werkator.build.BuildResultRepository
import de.hoennig.gittally.server.UiFormats import de.hoennig.werkator.server.UiFormats
import org.springframework.stereotype.Component import org.springframework.stereotype.Component
import picocli.CommandLine.Command import picocli.CommandLine.Command
import picocli.CommandLine.ExitCode import picocli.CommandLine.ExitCode
src/main/kotlin/de/hoennig/gittally/commands/SystemdServiceFiles.kt
+13 -13
View File
@@ -1,21 +1,21 @@
package de.hoennig.gittally.commands package de.hoennig.werkator.commands
import java.nio.file.Path import java.nio.file.Path
/** /**
* Generates the content of the systemd user unit and its `EnvironmentFile` for running * 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). * without the self-copy/self-update machinery (the unit points at the jar in place).
*/ */
object SystemdServiceFiles { 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. */ /** Host-global unit names of the nightly Docker cleanup — shared by all werkator repositories on the host. */
const val PRUNE_SERVICE_NAME = "gittally-docker-prune.service" const val PRUNE_SERVICE_NAME = "werkator-docker-prune.service"
const val PRUNE_TIMER_NAME = "gittally-docker-prune.timer" const val PRUNE_TIMER_NAME = "werkator-docker-prune.timer"
/** Per-repository unit name, because one GitTally instance serves exactly one repository. */ /** Per-repository unit name, because one werkator instance serves exactly one repository. */
fun unitName(repoRoot: Path): String = "gittally-${sanitize(repoRoot.fileName.toString())}.service" fun unitName(repoRoot: Path): String = "werkator-${sanitize(repoRoot.fileName.toString())}.service"
fun unitFileContent( fun unitFileContent(
repoRoot: Path, repoRoot: Path,
@@ -25,7 +25,7 @@ object SystemdServiceFiles {
): String = ): String =
""" """
[Unit] [Unit]
Description=GitTally CI for ${repoRoot.fileName} Description=werkator CI for ${repoRoot.fileName}
Wants=network-online.target Wants=network-online.target
After=network-online.target docker.service After=network-online.target docker.service
@@ -49,7 +49,7 @@ object SystemdServiceFiles {
fun pruneServiceContent(): String = fun pruneServiceContent(): String =
""" """
[Unit] [Unit]
Description=Clean up unused Docker containers and images (GitTally) Description=Clean up unused Docker containers and images (werkator)
[Service] [Service]
Type=oneshot Type=oneshot
@@ -62,7 +62,7 @@ object SystemdServiceFiles {
fun pruneTimerContent(): String = fun pruneTimerContent(): String =
""" """
[Unit] [Unit]
Description=Nightly Docker cleanup before the auto builds (GitTally) Description=Nightly Docker cleanup before the auto builds (werkator)
[Timer] [Timer]
OnCalendar=*-*-* 02:00:00 OnCalendar=*-*-* 02:00:00
@@ -74,8 +74,8 @@ object SystemdServiceFiles {
fun envFileContent(): String = fun envFileContent(): String =
""" """
# EnvironmentFile for the GitTally systemd service. # EnvironmentFile for the werkator systemd service.
# GitTally itself is configured via .gittally.yml and .git/gittally/.gittally.yml, # werkator itself is configured via .werkator.yml and .git/werkator/.werkator.yml,
# not via environment variables; this file only tunes the JVM process. # not via environment variables; this file only tunes the JVM process.
#JAVA_OPTS=-Xmx256m #JAVA_OPTS=-Xmx256m
""".trimIndent() + "\n" """.trimIndent() + "\n"
src/main/kotlin/de/hoennig/gittally/config/BuildDefinition.kt
+1 -1
View File
@@ -1,4 +1,4 @@
package de.hoennig.gittally.config package de.hoennig.werkator.config
import java.time.Duration import java.time.Duration
import java.time.Instant import java.time.Instant
src/main/kotlin/de/hoennig/gittally/config/ConfigLoader.kt
+25 -25
View File
@@ -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.DeserializationFeature
import com.fasterxml.jackson.databind.ObjectMapper import com.fasterxml.jackson.databind.ObjectMapper
@@ -17,7 +17,7 @@ import java.util.concurrent.ConcurrentHashMap
@Service @Service
class ConfigLoader( 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 buildProperties: ObjectProvider<BuildProperties>? = null,
) { ) {
private val log = LoggerFactory.getLogger(ConfigLoader::class.java) 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. */ /** Section-level warnings already reported, keyed by a fixed slug; the config is loaded on every poll cycle. */
private val warnedSections = ConcurrentHashMap.newKeySet<String>() 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, * (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]. * to [load].
*/ */
fun loadForWorktree( fun loadForWorktree(
workingDir: Path, workingDir: Path,
worktreeDir: Path, worktreeDir: Path,
): GitTallyConfig = withBranchLayer(workingDir, loadFile(worktreeDir.resolve(".gittally.yml").toFile())) ): WerkatorConfig = withBranchLayer(workingDir, loadFile(worktreeDir.resolve(".werkator.yml").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: * ([branchConfigYaml], null or blank for a branch without one) merged on top:
* precedence branch > `.git` > project. A branch describes its own CI — build * precedence branch > `.git` > project. A branch describes its own CI — build
* settings (`buildCommand`, `cleanCommand`, `artifactDirs`, `docker.image`/`env`, …) * settings (`buildCommand`, `cleanCommand`, `artifactDirs`, `docker.image`/`env`, …)
@@ -70,25 +70,25 @@ class ConfigLoader(
fun loadWithBranchLayer( fun loadWithBranchLayer(
workingDir: Path, workingDir: Path,
branchConfigYaml: String?, branchConfigYaml: String?,
): GitTallyConfig = withBranchLayer(workingDir, parseYaml(branchConfigYaml)) ): WerkatorConfig = withBranchLayer(workingDir, parseYaml(branchConfigYaml))
private fun withBranchLayer( private fun withBranchLayer(
workingDir: Path, workingDir: Path,
branchLayer: Map<String, Any?>, branchLayer: Map<String, Any?>,
): GitTallyConfig { ): WerkatorConfig {
// scoped to this branch: an incompatible branch config fails its own builds and // 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 // must never stop the server or hold up the branches that are fine
checkVersion(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 .gittally.yml of this branch", BRANCH_HINT) checkTriggerBlocks(branchLayer, "the committed .werkator.yml of this branch", BRANCH_HINT)
return toConfig(deepMerge(loadRaw(workingDir), stripPinned(branchLayer))) 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 = val config =
if (raw.isEmpty()) { if (raw.isEmpty()) {
GitTallyConfig() WerkatorConfig()
} else { } else {
yaml.convertValue(resolveBuildSections(dropNonDefinitionBuilds(raw)), GitTallyConfig::class.java) yaml.convertValue(resolveBuildSections(dropNonDefinitionBuilds(raw)), WerkatorConfig::class.java)
} }
return defaultPublicBaseUrl(config) return defaultPublicBaseUrl(config)
} }
@@ -265,7 +265,7 @@ class ConfigLoader(
} }
/** Legacy default: an empty `server.publicBaseUrl` becomes `https://<nginx.serverName>/`. */ /** 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() || if (config.server.publicBaseUrl.isNotBlank() ||
config.server.nginx.serverName config.server.nginx.serverName
.isBlank() .isBlank()
@@ -276,18 +276,18 @@ class ConfigLoader(
} }
fun loadRaw(workingDir: Path = Paths.get(".")): Map<String, Any?> { fun loadRaw(workingDir: Path = Paths.get(".")): Map<String, Any?> {
val repoInstall = loadFile(workingDir.resolve(".git/gittally/.gittally.yml").toFile()) val repoInstall = loadFile(workingDir.resolve(".git/werkator/.werkator.yml").toFile())
val project = loadFile(workingDir.resolve(".gittally.yml").toFile()) val project = loadFile(workingDir.resolve(".werkator.yml").toFile())
// per file, so the message names the file to fix — the merged map has no provenance // per file, so the message names the file to fix — the merged map has no provenance
checkVersion(project, ".gittally.yml", ROLLBACK_HINT) checkVersion(project, ".werkator.yml", ROLLBACK_HINT)
checkVersion(repoInstall, ".git/gittally/.gittally.yml", ROLLBACK_HINT) checkVersion(repoInstall, ".git/werkator/.werkator.yml", ROLLBACK_HINT)
checkTriggerBlocks(project, ".gittally.yml", ROLLBACK_HINT) checkTriggerBlocks(project, ".werkator.yml", ROLLBACK_HINT)
checkTriggerBlocks(repoInstall, ".git/gittally/.gittally.yml", ROLLBACK_HINT) checkTriggerBlocks(repoInstall, ".git/werkator/.werkator.yml", ROLLBACK_HINT)
return deepMerge(project, repoInstall) 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 * 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 * 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 * its own `below` marker is a warning, logged once: an unmaintained marker must
@@ -314,7 +314,7 @@ class ConfigLoader(
@Suppress("UNCHECKED_CAST") @Suppress("UNCHECKED_CAST")
private fun requirementOf(raw: Map<String, Any?>): VersionRequirement { 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( return VersionRequirement(
since = version["since"]?.toString()?.trim().orEmpty(), since = version["since"]?.toString()?.trim().orEmpty(),
below = version["below"]?.toString()?.trim().orEmpty(), below = version["below"]?.toString()?.trim().orEmpty(),
@@ -329,7 +329,7 @@ class ConfigLoader(
return yaml.readValue(file, Map::class.java) as Map<String, Any?> 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?> { private fun parseYaml(text: String?): Map<String, Any?> {
if (text.isNullOrBlank()) return emptyMap() if (text.isNullOrBlank()) return emptyMap()
@Suppress("UNCHECKED_CAST") @Suppress("UNCHECKED_CAST")
@@ -411,7 +411,7 @@ class ConfigLoader(
private const val NO_TRIGGER_WARNING = "no-build-triggered" private const val NO_TRIGGER_WARNING = "no-build-triggered"
private const val ROLLBACK_HINT = 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 = private const val BRANCH_HINT =
"Migrate the file on this branch; the other branches keep building." "Migrate the file on this branch; the other branches keep building."
src/main/kotlin/de/hoennig/gittally/config/ConfigVersion.kt
+20 -20
View File
@@ -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: * section:
* *
* ```yaml * ```yaml
* gitTally: * werkator:
* version: * version:
* since: "0.9.16" # always hard: an older GitTally refuses this file * since: "0.9.16" # always hard: an older werkator refuses this file
* below: "2.0" # GitTally decides how hard, see ConfigVersions.verdict * 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 * 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, * is ever supported. The declared version exists to make an incompatibility nameable,
* never to run two parsers. * never to run two parsers.
*/ */
data class VersionRequirement( 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 = "", 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 = "", val below: String = "",
) )
data class GitTallyMeta( data class werkatorMeta(
val version: VersionRequirement = VersionRequirement(), 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 { sealed interface VersionVerdict {
/** The running version is covered by the declaration. */ /** The running version is covered by the declaration. */
data object Compatible : VersionVerdict data object Compatible : VersionVerdict
@@ -37,24 +37,24 @@ sealed interface VersionVerdict {
val message: String, val message: String,
) : VersionVerdict ) : 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( data class Incompatible(
val message: String, val message: String,
) : VersionVerdict ) : 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( open class ConfigException(
message: String, message: String,
) : RuntimeException(message) ) : 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( class ConfigVersionException(
message: String, message: String,
) : ConfigException(message) ) : 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. * a key that moved and is silently ignored means a build that quietly stops happening.
*/ */
class ConfigFormatException( class ConfigFormatException(
@@ -64,7 +64,7 @@ class ConfigFormatException(
object ConfigVersions { object ConfigVersions {
/** /**
* The version in which the configuration format last changed incompatibly — a file * 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 * happened; set it to the release that introduces one, together with the migration
* note the message points at. * note the message points at.
*/ */
@@ -76,13 +76,13 @@ object ConfigVersions {
/** /**
* Decides what [requirement] means for [running]. * 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 * silently ignoring its unknown keys is exactly the failure mode this section exists
* to prevent. * to prevent.
* *
* `below` alone only warns: it is the team's release marker, and an unmaintained * `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 * 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. * and read after it is incompatible regardless of what it declares as its ceiling.
*/ */
fun verdict( fun verdict(
@@ -95,13 +95,13 @@ object ConfigVersions {
val since = parse(requirement.since) val since = parse(requirement.since)
if (since != null && version < since) { if (since != null && version < since) {
return VersionVerdict.Incompatible( 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) val broke = parse(brokeIn)
if (since != null && broke != null && since < broke && version >= broke) { if (since != null && broke != null && since < broke && version >= broke) {
return VersionVerdict.Incompatible( 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" + "but the configuration format changed incompatibly in $brokeIn" +
brokeDescription.takeIf { it.isNotBlank() }?.let { ": $it" }.orEmpty(), brokeDescription.takeIf { it.isNotBlank() }?.let { ": $it" }.orEmpty(),
) )
@@ -109,7 +109,7 @@ object ConfigVersions {
val below = parse(requirement.below) val below = parse(requirement.below)
if (below != null && version >= below) { if (below != null && version >= below) {
return VersionVerdict.Warn( 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 return VersionVerdict.Compatible
src/main/kotlin/de/hoennig/gittally/config/DurationParser.kt
+1 -1
View File
@@ -1,4 +1,4 @@
package de.hoennig.gittally.config package de.hoennig.werkator.config
import java.time.Duration import java.time.Duration
src/main/kotlin/de/hoennig/gittally/config/GitTallyConfig.kt → src/main/kotlin/de/hoennig/gittally/config/WerkatorConfig.kt
+10 -10
View File
@@ -1,10 +1,10 @@
package de.hoennig.gittally.config package de.hoennig.werkator.config
import com.fasterxml.jackson.annotation.JsonProperty import com.fasterxml.jackson.annotation.JsonProperty
data class GitTallyConfig( data class WerkatorConfig(
/** What this file declares about the GitTally that reads it; see [VersionRequirement]. */ /** What this file declares about the werkator that reads it; see [VersionRequirement]. */
val gitTally: GitTallyMeta = GitTallyMeta(), val werkator: werkatorMeta = werkatorMeta(),
val server: ServerConfig = ServerConfig(), val server: ServerConfig = ServerConfig(),
val git: GitConfig = GitConfig(), val git: GitConfig = GitConfig(),
val gitea: GiteaConfig = GiteaConfig(), 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 * for hosts without a usable reverse proxy (ADR 0005). Off by default; the
* reverse-proxy deployment from `docs/deployment.md` stays the recommended setup. * reverse-proxy deployment from `docs/deployment.md` stays the recommended setup.
*/ */
@@ -76,11 +76,11 @@ data class NginxConfig(
val httpsPort: Int = 8443, val httpsPort: Int = 8443,
/** Host nginx proxies to; empty uses [serverName] (the container cannot reach `localhost`). */ /** Host nginx proxies to; empty uses [serverName] (the container cannot reach `localhost`). */
val upstreamHost: String = "", 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 = "", val containerName: String = "",
/** /**
* Directory for nginx config, certificates, and logs; empty means the platform * 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 = "", val stateDir: String = "",
/** E-mail for the Let's Encrypt account; empty registers without one. */ /** E-mail for the Let's Encrypt account; empty registers without one. */
@@ -96,7 +96,7 @@ data class GiteaConfig(
val baseUrl: String = "", val baseUrl: String = "",
val owner: String = "", val owner: String = "",
val repo: String = "", val repo: String = "",
val statusContext: String = "GitTally", val statusContext: String = "werkator",
) )
data class ArtifactsConfig( data class ArtifactsConfig(
@@ -117,7 +117,7 @@ data class ArtifactsConfig(
val keepLatestGreen: Boolean = true, val keepLatestGreen: Boolean = true,
/** /**
* Root directory for stored build artifacts; empty means the platform default * 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 = "", val rootDir: String = "",
) )
@@ -130,7 +130,7 @@ data class WatcherConfig(
* Honor the `branches.<name>.requirePullRequest` gates. Set false for a plain git * Honor the `branches.<name>.requirePullRequest` gates. Set false for a plain git
* origin without pull-request refs (no Gitea/GitHub) — gated branches then build * origin without pull-request refs (no Gitea/GitHub) — gated branches then build
* on new commits like any other branch. Typically overridden per machine in * 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, val pullRequestGate: Boolean = true,
/** /**
src/main/kotlin/de/hoennig/gittally/git/GitAskPass.kt
+6 -6
View File
@@ -1,4 +1,4 @@
package de.hoennig.gittally.git package de.hoennig.werkator.git
import java.nio.file.Files import java.nio.file.Files
import java.nio.file.attribute.PosixFilePermissions import java.nio.file.attribute.PosixFilePermissions
@@ -15,10 +15,10 @@ object GitAskPass {
#!/bin/sh #!/bin/sh
case "${'$'}1" in case "${'$'}1" in
*[Uu]sername*) *[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 esac
""".trimIndent() + "\n" """.trimIndent() + "\n"
@@ -30,7 +30,7 @@ object GitAskPass {
): T { ): T {
val script = val script =
Files.createTempFile( Files.createTempFile(
"gittally-askpass", "werkator-askpass",
".sh", ".sh",
PosixFilePermissions.asFileAttribute(PosixFilePermissions.fromString("rwx------")), PosixFilePermissions.asFileAttribute(PosixFilePermissions.fromString("rwx------")),
) )
@@ -40,8 +40,8 @@ object GitAskPass {
mapOf( mapOf(
"GIT_ASKPASS" to script.toAbsolutePath().toString(), "GIT_ASKPASS" to script.toAbsolutePath().toString(),
"GIT_TERMINAL_PROMPT" to "0", "GIT_TERMINAL_PROMPT" to "0",
"GITTALLY_GIT_ACCOUNT" to account, "werkator_GIT_ACCOUNT" to account,
"GITTALLY_GIT_TOKEN" to token, "werkator_GIT_TOKEN" to token,
), ),
) )
} finally { } finally {
src/main/kotlin/de/hoennig/gittally/git/GitCommandRunner.kt
+1 -1
View File
@@ -1,4 +1,4 @@
package de.hoennig.gittally.git package de.hoennig.werkator.git
import org.springframework.stereotype.Component import org.springframework.stereotype.Component
import java.nio.file.Path import java.nio.file.Path
src/main/kotlin/de/hoennig/gittally/git/GitService.kt
+3 -3
View File
@@ -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.slf4j.LoggerFactory
import org.springframework.stereotype.Service import org.springframework.stereotype.Service
import java.nio.file.Path 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 * 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( fun showFileAtCommit(
commit: String, commit: String,
src/main/kotlin/de/hoennig/gittally/gitea/GiteaClient.kt
+6 -6
View File
@@ -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.JacksonException
import com.fasterxml.jackson.core.type.TypeReference import com.fasterxml.jackson.core.type.TypeReference
import com.fasterxml.jackson.databind.DeserializationFeature import com.fasterxml.jackson.databind.DeserializationFeature
import com.fasterxml.jackson.databind.ObjectMapper import com.fasterxml.jackson.databind.ObjectMapper
import com.fasterxml.jackson.module.kotlin.registerKotlinModule import com.fasterxml.jackson.module.kotlin.registerKotlinModule
import de.hoennig.gittally.build.BuildStatus import de.hoennig.werkator.build.BuildStatus
import de.hoennig.gittally.config.ConfigLoader import de.hoennig.werkator.config.ConfigLoader
import de.hoennig.gittally.config.GitTallyConfig import de.hoennig.werkator.config.WerkatorConfig
import org.slf4j.LoggerFactory import org.slf4j.LoggerFactory
import org.springframework.http.MediaType import org.springframework.http.MediaType
import org.springframework.http.client.JdkClientHttpRequestFactory 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.baseUrl.isNotBlank() &&
config.gitea.owner.isNotBlank() && config.gitea.owner.isNotBlank() &&
config.gitea.repo.isNotBlank() && config.gitea.repo.isNotBlank() &&
@@ -182,7 +182,7 @@ class GiteaClient(
HttpClient.newBuilder().connectTimeout(REQUEST_TIMEOUT).build(), HttpClient.newBuilder().connectTimeout(REQUEST_TIMEOUT).build(),
).apply { setReadTimeout(REQUEST_TIMEOUT) } ).apply { setReadTimeout(REQUEST_TIMEOUT) }
private fun restClient(config: GitTallyConfig): RestClient = private fun restClient(config: WerkatorConfig): RestClient =
RestClient RestClient
.builder() .builder()
.requestFactory(requestFactory) .requestFactory(requestFactory)
src/main/kotlin/de/hoennig/gittally/gitea/GiteaStateMapping.kt
+2 -2
View File
@@ -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. * Gitea commit-status state published for this build status.
src/main/kotlin/de/hoennig/gittally/metrics/MetricsConfiguration.kt
+2 -2
View File
@@ -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.Bean
import org.springframework.context.annotation.Configuration import org.springframework.context.annotation.Configuration
import java.time.Clock import java.time.Clock
src/main/kotlin/de/hoennig/gittally/metrics/SystemMetrics.kt
+1 -1
View File
@@ -1,4 +1,4 @@
package de.hoennig.gittally.metrics package de.hoennig.werkator.metrics
import java.time.Instant import java.time.Instant
src/main/kotlin/de/hoennig/gittally/metrics/SystemMetricsCollector.kt
+3 -3
View File
@@ -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.DeserializationFeature
import com.fasterxml.jackson.databind.ObjectMapper 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. * repository size every 60 seconds and keeps running min/max/avg per metric.
* The aggregation state is persisted, so restarts continue the series. * The aggregation state is persisted, so restarts continue the series.
* Every source degrades gracefully: an unreadable source makes its metric null * 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). * nothing is scheduled until [start] is called (server mode only).
*/ */
class SystemMetricsCollector( class SystemMetricsCollector(
@@ -83,7 +83,7 @@ class SystemMetricsCollector(
scheduler = scheduler =
Executors Executors
.newSingleThreadScheduledExecutor { runnable -> .newSingleThreadScheduledExecutor { runnable ->
Thread(runnable, "gittally-metrics").apply { isDaemon = true } Thread(runnable, "werkator-metrics").apply { isDaemon = true }
}.also { }.also {
it.scheduleWithFixedDelay(::sampleSafely, 0, SAMPLE_INTERVAL_SECONDS, TimeUnit.SECONDS) it.scheduleWithFixedDelay(::sampleSafely, 0, SAMPLE_INTERVAL_SECONDS, TimeUnit.SECONDS)
} }
src/main/kotlin/de/hoennig/gittally/server/ApiDtos.kt
+3 -3
View File
@@ -1,7 +1,7 @@
package de.hoennig.gittally.server package de.hoennig.werkator.server
import de.hoennig.gittally.build.BuildResult import de.hoennig.werkator.build.BuildResult
import de.hoennig.gittally.build.BuildStatus import de.hoennig.werkator.build.BuildStatus
import java.time.Instant import java.time.Instant
/** JSON statuses are lowercase like the legacy TSV/HTML statuses. */ /** JSON statuses are lowercase like the legacy TSV/HTML statuses. */
src/main/kotlin/de/hoennig/gittally/server/ArtifactFileController.kt
+2 -2
View File
@@ -1,6 +1,6 @@
package de.hoennig.gittally.server package de.hoennig.werkator.server
import de.hoennig.gittally.build.ArtifactStore import de.hoennig.werkator.build.ArtifactStore
import jakarta.servlet.http.HttpServletRequest import jakarta.servlet.http.HttpServletRequest
import org.springframework.core.io.FileSystemResource import org.springframework.core.io.FileSystemResource
import org.springframework.core.io.Resource import org.springframework.core.io.Resource
src/main/kotlin/de/hoennig/gittally/server/BranchListing.kt
+3 -3
View File
@@ -1,7 +1,7 @@
package de.hoennig.gittally.server package de.hoennig.werkator.server
import de.hoennig.gittally.build.BuildResultRepository import de.hoennig.werkator.build.BuildResultRepository
import de.hoennig.gittally.git.GitService import de.hoennig.werkator.git.GitService
import org.springframework.stereotype.Component import org.springframework.stereotype.Component
import java.nio.file.Path import java.nio.file.Path
import java.nio.file.Paths import java.nio.file.Paths
src/main/kotlin/de/hoennig/gittally/server/BranchPermalinks.kt
+4 -4
View File
@@ -1,8 +1,8 @@
package de.hoennig.gittally.server package de.hoennig.werkator.server
import de.hoennig.gittally.build.ArtifactKeys import de.hoennig.werkator.build.ArtifactKeys
import de.hoennig.gittally.build.BuildResult import de.hoennig.werkator.build.BuildResult
import de.hoennig.gittally.build.BuildResultRepository import de.hoennig.werkator.build.BuildResultRepository
import org.springframework.http.HttpStatus import org.springframework.http.HttpStatus
import org.springframework.stereotype.Component import org.springframework.stereotype.Component
import org.springframework.web.server.ResponseStatusException import org.springframework.web.server.ResponseStatusException
src/main/kotlin/de/hoennig/gittally/server/BuildsApiController.kt
+9 -9
View File
@@ -1,12 +1,12 @@
package de.hoennig.gittally.server package de.hoennig.werkator.server
import de.hoennig.gittally.build.ArtifactStore import de.hoennig.werkator.build.ArtifactStore
import de.hoennig.gittally.build.BuildExecutor import de.hoennig.werkator.build.BuildExecutor
import de.hoennig.gittally.build.BuildResult import de.hoennig.werkator.build.BuildResult
import de.hoennig.gittally.build.BuildResultRepository import de.hoennig.werkator.build.BuildResultRepository
import de.hoennig.gittally.build.BuildStatus import de.hoennig.werkator.build.BuildStatus
import de.hoennig.gittally.config.BuildDefinition import de.hoennig.werkator.config.BuildDefinition
import de.hoennig.gittally.git.GitService import de.hoennig.werkator.git.GitService
import org.springframework.http.HttpStatus import org.springframework.http.HttpStatus
import org.springframework.http.ResponseEntity import org.springframework.http.ResponseEntity
import org.springframework.web.bind.annotation.DeleteMapping import org.springframework.web.bind.annotation.DeleteMapping
@@ -192,7 +192,7 @@ class BuildsApiController(
} }
companion object { companion object {
const val TOKEN_HEADER = "X-GitTally-Token" const val TOKEN_HEADER = "X-werkator-Token"
private const val MAX_LOG_CHUNK = 1024L * 1024L private const val MAX_LOG_CHUNK = 1024L * 1024L
} }
} }
src/main/kotlin/de/hoennig/gittally/server/ControlTokenService.kt
+2 -2
View File
@@ -1,6 +1,6 @@
package de.hoennig.gittally.server package de.hoennig.werkator.server
import de.hoennig.gittally.SecretFiles import de.hoennig.werkator.SecretFiles
import java.nio.file.Files import java.nio.file.Files
import java.nio.file.Path import java.nio.file.Path
import java.security.MessageDigest import java.security.MessageDigest
src/main/kotlin/de/hoennig/gittally/server/NginxConfigFiles.kt
+2 -2
View File
@@ -1,4 +1,4 @@
package de.hoennig.gittally.server package de.hoennig.werkator.server
/** /**
* Generates the nginx configuration for the managed proxy container, ported from * Generates the nginx configuration for the managed proxy container, ported from
@@ -12,7 +12,7 @@ object NginxConfigFiles {
* The `nginx.conf` content. Without [full] it is the init config for the * The `nginx.conf` content. Without [full] it is the init config for the
* two-phase startup: HTTP only, serving the ACME webroot challenge and * two-phase startup: HTTP only, serving the ACME webroot challenge and
* redirecting everything else to HTTPS. With [full] an HTTPS server block * redirecting everything else to HTTPS. With [full] an HTTPS server block
* with the Let's Encrypt certificate and the proxy to GitTally is added. * with the Let's Encrypt certificate and the proxy to werkator is added.
*/ */
fun nginxConf( fun nginxConf(
serverName: String, serverName: String,
src/main/kotlin/de/hoennig/gittally/server/NginxProxyManager.kt
+20 -20
View File
@@ -1,9 +1,9 @@
package de.hoennig.gittally.server package de.hoennig.werkator.server
import de.hoennig.gittally.build.ArtifactKeys import de.hoennig.werkator.build.ArtifactKeys
import de.hoennig.gittally.build.DockerBuildRunner.Companion.GITTALLY_LABEL import de.hoennig.werkator.build.DockerBuildRunner.Companion.werkator_LABEL
import de.hoennig.gittally.config.ConfigLoader import de.hoennig.werkator.config.ConfigLoader
import de.hoennig.gittally.git.GitCommandRunner import de.hoennig.werkator.git.GitCommandRunner
import org.slf4j.LoggerFactory import org.slf4j.LoggerFactory
import org.springframework.stereotype.Component import org.springframework.stereotype.Component
import java.nio.file.Files import java.nio.file.Files
@@ -11,10 +11,10 @@ import java.nio.file.Path
import java.nio.file.Paths import java.nio.file.Paths
/** /**
* Manages the opt-in nginx+certbot Docker container that serves GitTally over * Manages the opt-in nginx+certbot Docker container that serves werkator over
* HTTPS on hosts without a reverse proxy (ADR 0005), ported from the legacy * HTTPS on hosts without a reverse proxy (ADR 0005), ported from the legacy
* `start_artifact_nginx` subsystem. Shells out to the `docker` CLI via the * `start_artifact_nginx` subsystem. Shells out to the `docker` CLI via the
* generic [GitCommandRunner] process wrapper, like [de.hoennig.gittally.build.DockerBuildRunner]. * generic [GitCommandRunner] process wrapper, like [de.hoennig.werkator.build.DockerBuildRunner].
* *
* Startup is two-phase: an HTTP-only init config serves the ACME webroot * Startup is two-phase: an HTTP-only init config serves the ACME webroot
* challenge, the certificate is obtained via a certbot container, then nginx is * challenge, the certificate is obtained via a certbot container, then nginx is
@@ -197,7 +197,7 @@ class NginxProxyManager(
/** /**
* Legacy `cleanup_stale_artifact_nginx_containers`: remove the container by * Legacy `cleanup_stale_artifact_nginx_containers`: remove the container by
* name, all nginx-role containers of this repository by label, and any * name, all nginx-role containers of this repository by label, and any
* GitTally container still occupying the configured ports. * werkator container still occupying the configured ports.
*/ */
private fun cleanupStaleContainers(settings: NginxSettings) { private fun cleanupStaleContainers(settings: NginxSettings) {
commandRunner.run(listOf("docker", "rm", "-f", settings.containerName), workingDir) commandRunner.run(listOf("docker", "rm", "-f", settings.containerName), workingDir)
@@ -208,11 +208,11 @@ class NginxProxyManager(
"ps", "ps",
"-aq", "-aq",
"--filter", "--filter",
"label=$GITTALLY_LABEL=true", "label=$werkator_LABEL=true",
"--filter", "--filter",
"label=$GITTALLY_LABEL.repository=${settings.repoKey}", "label=$werkator_LABEL.repository=${settings.repoKey}",
"--filter", "--filter",
"label=$GITTALLY_LABEL.role=nginx", "label=$werkator_LABEL.role=nginx",
), ),
workingDir, workingDir,
) )
@@ -220,11 +220,11 @@ class NginxProxyManager(
commandRunner.run(listOf("docker", "rm", "-f") + labelled.lines(), workingDir) commandRunner.run(listOf("docker", "rm", "-f") + labelled.lines(), workingDir)
} }
for (container in listContainersUsingPorts(settings)) { for (container in listContainersUsingPorts(settings)) {
if (container.labels.contains("$GITTALLY_LABEL=true") || if (container.labels.contains("$werkator_LABEL=true") ||
container.name.startsWith("gittally-") || container.name.startsWith("werkator-") ||
container.name.startsWith("git-watch-origin-and-test-nginx-") container.name.startsWith("git-watch-origin-and-test-nginx-")
) { ) {
log.info("removing stale GitTally container using an nginx port: {}", container.name) log.info("removing stale werkator container using an nginx port: {}", container.name)
commandRunner.run(listOf("docker", "rm", "-f", container.id), workingDir) commandRunner.run(listOf("docker", "rm", "-f", container.id), workingDir)
} }
} }
@@ -303,11 +303,11 @@ class NginxProxyManager(
"--volume", "--volume",
"${settings.nginxConf}:/etc/nginx/nginx.conf:ro", "${settings.nginxConf}:/etc/nginx/nginx.conf:ro",
"--label", "--label",
"$GITTALLY_LABEL=true", "$werkator_LABEL=true",
"--label", "--label",
"$GITTALLY_LABEL.repository=${settings.repoKey}", "$werkator_LABEL.repository=${settings.repoKey}",
"--label", "--label",
"$GITTALLY_LABEL.role=nginx", "$werkator_LABEL.role=nginx",
"nginx", "nginx",
) )
@@ -405,16 +405,16 @@ class NginxProxyManager(
System.getenv("XDG_STATE_HOME")?.takeIf { it.isNotBlank() }?.let { Paths.get(it) } System.getenv("XDG_STATE_HOME")?.takeIf { it.isNotBlank() }?.let { Paths.get(it) }
?: Paths.get(System.getProperty("user.home"), ".local", "state") ?: Paths.get(System.getProperty("user.home"), ".local", "state")
return stateHome return stateHome
.resolve("gittally") .resolve("werkator")
.resolve("nginx") .resolve("nginx")
.resolve(ArtifactKeys.repoKey(repoDir)) .resolve(ArtifactKeys.repoKey(repoDir))
.toAbsolutePath() .toAbsolutePath()
.normalize() .normalize()
} }
/** Legacy default `gittally-nginx-<repo-name>` with unsafe characters replaced. */ /** Legacy default `werkator-nginx-<repo-name>` with unsafe characters replaced. */
fun defaultContainerName(repoDir: Path): String = fun defaultContainerName(repoDir: Path): String =
"gittally-nginx-" + repoDir.fileName.toString().replace(Regex("[^A-Za-z0-9_.-]"), "-") "werkator-nginx-" + repoDir.fileName.toString().replace(Regex("[^A-Za-z0-9_.-]"), "-")
/** /**
* Certbot's pinned DH parameters (RFC 7919 ffdhe2048), bundled as a resource: * Certbot's pinned DH parameters (RFC 7919 ffdhe2048), bundled as a resource:
src/main/kotlin/de/hoennig/gittally/server/ServerConfiguration.kt
+2 -2
View File
@@ -1,4 +1,4 @@
package de.hoennig.gittally.server package de.hoennig.werkator.server
import org.springframework.context.annotation.Bean import org.springframework.context.annotation.Bean
import org.springframework.context.annotation.Configuration import org.springframework.context.annotation.Configuration
@@ -12,5 +12,5 @@ class ServerConfiguration {
* until the first guarded request, so the bean is safe outside a git repository. * until the first guarded request, so the bean is safe outside a git repository.
*/ */
@Bean @Bean
fun controlTokenService(): ControlTokenService = ControlTokenService(Paths.get(".git/gittally/control-token")) fun controlTokenService(): ControlTokenService = ControlTokenService(Paths.get(".git/werkator/control-token"))
} }
src/main/kotlin/de/hoennig/gittally/server/ServerMetricsLifecycle.kt
+2 -2
View File
@@ -1,6 +1,6 @@
package de.hoennig.gittally.server package de.hoennig.werkator.server
import de.hoennig.gittally.metrics.SystemMetricsCollector import de.hoennig.werkator.metrics.SystemMetricsCollector
import jakarta.annotation.PreDestroy import jakarta.annotation.PreDestroy
import org.springframework.boot.context.event.ApplicationReadyEvent import org.springframework.boot.context.event.ApplicationReadyEvent
import org.springframework.context.annotation.Profile import org.springframework.context.annotation.Profile
src/main/kotlin/de/hoennig/gittally/server/ServerNginxLifecycle.kt
+2 -2
View File
@@ -1,4 +1,4 @@
package de.hoennig.gittally.server package de.hoennig.werkator.server
import jakarta.annotation.PreDestroy import jakarta.annotation.PreDestroy
import org.springframework.boot.context.event.ApplicationReadyEvent import org.springframework.boot.context.event.ApplicationReadyEvent
@@ -26,7 +26,7 @@ class ServerNginxLifecycle(
/** Replaceable for tests: the scheduler running startup and renewal checks. */ /** Replaceable for tests: the scheduler running startup and renewal checks. */
internal var schedulerFactory: () -> ScheduledExecutorService = { internal var schedulerFactory: () -> ScheduledExecutorService = {
Executors.newSingleThreadScheduledExecutor { runnable -> Executors.newSingleThreadScheduledExecutor { runnable ->
Thread(runnable, "gittally-nginx").apply { isDaemon = true } Thread(runnable, "werkator-nginx").apply { isDaemon = true }
} }
} }
src/main/kotlin/de/hoennig/gittally/server/ServerWatcherLifecycle.kt
+2 -2
View File
@@ -1,6 +1,6 @@
package de.hoennig.gittally.server package de.hoennig.werkator.server
import de.hoennig.gittally.watcher.Watcher import de.hoennig.werkator.watcher.Watcher
import jakarta.annotation.PreDestroy import jakarta.annotation.PreDestroy
import org.springframework.boot.context.event.ApplicationReadyEvent import org.springframework.boot.context.event.ApplicationReadyEvent
import org.springframework.context.annotation.Profile import org.springframework.context.annotation.Profile
src/main/kotlin/de/hoennig/gittally/server/StatusApiController.kt
+4 -4
View File
@@ -1,8 +1,8 @@
package de.hoennig.gittally.server package de.hoennig.werkator.server
import de.hoennig.gittally.build.BuildResultRepository import de.hoennig.werkator.build.BuildResultRepository
import de.hoennig.gittally.gitea.GiteaClient import de.hoennig.werkator.gitea.GiteaClient
import de.hoennig.gittally.gitea.GiteaStatusResult import de.hoennig.werkator.gitea.GiteaStatusResult
import org.springframework.http.HttpStatus import org.springframework.http.HttpStatus
import org.springframework.http.ResponseEntity import org.springframework.http.ResponseEntity
import org.springframework.web.bind.annotation.GetMapping import org.springframework.web.bind.annotation.GetMapping

Some files were not shown because too many files have changed in this diff Show More