Renaming gitTally to Werkator because there is another git-related tool named gittally (#1)
* renaming from gitTally to Werkator * Rename GitTally to Werkator `gitTally` is the name of another product in the git space, so the rename is a precaution; nothing about what the build system does changes. The name follows one rule: `Werkator` where it is prose, capitalized where it is a Kotlin type and its file, lowercase everywhere a machine reads it — the command, packages, paths, configuration keys and values, the Gitea check context. Environment variables keep their convention and are uppercase throughout. Every configuration file is still found under its pre-rename name (`ConfigFiles`): `.gittally.yml` at the repository root, in a build worktree and as committed on a branch, `.git/gittally/.gittally.yml` for the machine layer. The current name wins where both exist, and the old file is then ignored rather than merged — two files side by side are a half-done rename, not a layering. Without the fallback an installation that updated without renaming would not fail: a configuration that is not found leaves every setting at its default, so it would come up looking healthy while having forgotten its credentials and its builds. `docs/werkator-migrationsplan.md` lists what the fallback does not cover and has to be moved by hand — above all the state directory `.git/werkator/`, which holds the build history, the control token and the worktrees, and has no fallback of its own. `docs/migration-from-legacy.md` is deleted with this: it mapped the legacy script's environment variables, and every host it addressed has long since moved to the YAML configuration. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> * Move the pre-rename state directory at the first start The configuration is found under either name, the state is not: build history, control token, auto-build slots and worktrees live at one fixed path. An installation that updates without moving `.git/gittally` would not fail — it would come up with an empty history and a fresh control token, quietly. So the first start moves it instead of the release notes asking for it. Only when the old directory exists and the new one does not. Where both exist nothing is touched and a warning names the leftover: which of the two is the live state is not something to guess. A failed move is an error in the log, never an abort — a CI must not hang on it. The worktrees are dropped rather than moved, since they point at their old path in both directions; `GitWorktreeWorkspaces` prunes the stale admin entry and recreates each on its branch's next build. A generated systemd unit moves with the directory and leaves its symlink dangling, which is warned about — the running service is unaffected, the next start is not. Runs from `CliRunner`, before any command resolves a path under the directory, and so before the second context of `server` exists. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> * Document PR#1: the rename to Werkator Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> * Drop the legacy env-to-YAML conversion from the setup tool The old bash script configured itself through `GITTALLY_*` environment variables. The blanket rename rewrote those literals, so the converter was looking for `WERKATOR_*` — a spelling no host has ever written. Fed a real legacy file it would have found nothing and written an almost empty configuration, without an error, which is the same silent failure this rename is otherwise careful to avoid. The conversion has served its purpose with the vm2176 to vm4006 migration, so it goes instead of being repaired. What remains is the setup of a new instance: the preconditions, the credential prompt, and the machine configuration written mode 600 — now carrying the host's public URL as well, since that is host-specific too. Everything the repository builds comes from `init` and its templates. It also stops emitting a legacy `branches:` section, which step 18 is about to reject outright. `docs/plan/00-legacy-analysis.md` and `13-nginx-tls.md` get the real `GITTALLY_*` spelling back: they record what the old script read. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> * Describe this repository's build with a build definition Its own `.werkator.yml` still used the deprecated `branches` section with an `autoBuild` schedule that was switched off. That section is read only while nothing defines a build at all, and step 18 rejects it by name — so this repository would have blocked the precondition of that step, which asks that no configuration still in play carries it. Nothing about the build changes: `builds.default` with `trigger.onPush` is a build of every new commit on every branch, which is what the branch section said. `config:print --full` resolves the definition completely and logs no deprecation warning any more. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> * Stop documenting the pre-rename fallback for users Exactly one repository is configured with the old names, and it is migrated by hand in the same move as this release. The fallback is therefore a transition of days, not a feature anyone reading the release notes or the configuration reference has to plan around. Removed from `releases.html` and `docs/configuration.md`. The mechanism itself is unchanged and stays described where it is worked on: in `ConfigFiles`, in `StateDirMigration`, and in the migration plan. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> * Bring the PR-doc to its final state The `statusContext` question is answered and marked as decided rather than left standing: it is the one value a human reads as a label, and it stays lowercase because Gitea matches it and the client reads it back, which makes it a value. Also records that the pre-rename fallback is deliberately absent from the release notes and the configuration reference. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> * Release v1.0.0: Werkator The release after 0.9.21 is 1.0.0, because a product that changes its name is better off counting from one under it. The release note says as much, so the jump is not read as a claim about maturity — plan steps 14, 17 and 18 are still open. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> * Correct the PR-doc about the version It claimed the PR carries no version bump, which the release commit made untrue, and records why the number is 1.0.0 instead of 0.9.22. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> * Point the legacy references at the history `legacy/gitTally` was removed from the tree with the rename, but the README still described it as a reference kept in the repository, and the plan told an executing session to read parts of it — including step 14, which is open. The README section is gone; `docs/plan/README.md`, step 14 and the legacy analysis now say where the script actually is (`git show 7f55068^:legacy/gitTally`). Executed steps and ADR 0004 keep their wording: they record what was true when they ran. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> * Retarget the links in the historic PR-docs The package rename moved every file the older PR-docs link to, leaving 60 dead links. Only the link targets are rewritten, never the visible text and never a statement: those documents record what was true when they were written, GitTally in the prose included. A snapshot may be outdated; it should still be navigable. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> * Add the v1.0.0 deployment procedure for vm4006 Measured, not estimated: the state directory is 878 MB, of which 878 MB are the nine build worktrees. What cannot be recreated is 84 KB, so the snapshot before an in-place switch is instant and the rollback is one sequence of moves. Records the three expected non-failures — a cold Gradle volume, one image rebuild, containers left under the old label — and that `gitea.statusContext` needs no attention because it comes from the watched repository's committed configuration. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> * Rename the machine configuration along with its directory Found by the deployment to vm4006: the move renames the directory and leaves the file inside it alone, so the machine configuration ended up at `.git/werkator/.gittally.yml` — a pair of names the lookup did not expect, because it pairs directory and file name. The instance resolved empty credentials, no public URL and none of the host's build definitions, and said nothing about it. That is the exact failure this change exists to prevent, produced by the change itself. `StateDirMigration` now renames the configuration with the directory, unless one under the current name is already there. `ConfigFiles` carries `.git/werkator/.gittally.yml` as a third candidate as well, for a directory somebody moved by hand, where the migration never runs and so can rename nothing. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> * Let init see a configuration under its previous name `init --systemd` runs `init`, and its "already exists" check knew only the current name. On the one repository still carrying `.gittally.yml` it therefore wrote a fresh template `.werkator.yml` beside it — and since the current name wins, that repository would have built the template's `./gradlew test` instead of what its own configuration says. Found on vm4006, where the file was created in the watched working tree and removed again by hand. Both checks now ask `ConfigFiles`, so init decides existence by the same rule the loader uses to read. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> * Record the v1.0.0 deployment to vm4006 Deployed from the branch as the final test of PR#1, and it did what a final test is for: it found two silent-failure defects before the service was started, both fixed and redeployed in the same window. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> * Drop the control token left under the old localStorage key The key is named after the product, so the rename left every browser with a token under `gittally.controlToken`, which nothing reads any more and which "forget token" can no longer reach. It is a write-scope token in a browser store, not a password, but a secret nobody owns is worth one line to remove. Removed on load. The token on the server is unchanged, so re-entering it once per browser is all the rename costs. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 5 <noreply@anthropic.com>
This commit is contained in:
Michael Hönnig
co-authored by
Claude Opus 5
Claude Opus 5
parent
4d76744721
commit
d0169e57bc
@@ -36,8 +36,8 @@ So that stale logs and reports do not stay on disk indefinitely.
|
||||
|
||||
##### Verified by
|
||||
|
||||
- [FileBuildResultRepositoryTest](../../src/test/kotlin/de/hoennig/gittally/build/FileBuildResultRepositoryTest.kt)
|
||||
- [WatcherTest](../../src/test/kotlin/de/hoennig/gittally/watcher/WatcherTest.kt)
|
||||
- [FileBuildResultRepositoryTest](../../src/test/kotlin/de/hoennig/werkator/build/FileBuildResultRepositoryTest.kt)
|
||||
- [WatcherTest](../../src/test/kotlin/de/hoennig/werkator/watcher/WatcherTest.kt)
|
||||
|
||||
#### Scenario#000.02: Count and age combine as independent caps
|
||||
|
||||
@@ -50,7 +50,7 @@ So that one config can bound disk usage by count and staleness by age at the sam
|
||||
|
||||
##### Verified by
|
||||
|
||||
- [FileBuildResultRepositoryTest](../../src/test/kotlin/de/hoennig/gittally/build/FileBuildResultRepositoryTest.kt)
|
||||
- [FileBuildResultRepositoryTest](../../src/test/kotlin/de/hoennig/werkator/build/FileBuildResultRepositoryTest.kt)
|
||||
|
||||
#### Scenario#000.03: A branch's newest build is never age-pruned
|
||||
|
||||
@@ -62,7 +62,7 @@ So that a dormant branch keeps its last build status visible, matching the legac
|
||||
|
||||
##### Verified by
|
||||
|
||||
- [FileBuildResultRepositoryTest](../../src/test/kotlin/de/hoennig/gittally/build/FileBuildResultRepositoryTest.kt)
|
||||
- [FileBuildResultRepositoryTest](../../src/test/kotlin/de/hoennig/werkator/build/FileBuildResultRepositoryTest.kt)
|
||||
|
||||
#### Scenario#000.04: keepLatestGreen shields the latest green build from the age limit
|
||||
|
||||
@@ -75,7 +75,7 @@ So that the permanent `/branches/<branch-key>/…` artifact links stay valid whi
|
||||
|
||||
##### Verified by
|
||||
|
||||
- [FileBuildResultRepositoryTest](../../src/test/kotlin/de/hoennig/gittally/build/FileBuildResultRepositoryTest.kt)
|
||||
- [FileBuildResultRepositoryTest](../../src/test/kotlin/de/hoennig/werkator/build/FileBuildResultRepositoryTest.kt)
|
||||
|
||||
#### Scenario#000.05: The default keeps existing behavior unchanged
|
||||
|
||||
@@ -87,7 +87,7 @@ So that existing installations are unaffected by the new key.
|
||||
|
||||
##### Verified by
|
||||
|
||||
- [FileBuildResultRepositoryTest](../../src/test/kotlin/de/hoennig/gittally/build/FileBuildResultRepositoryTest.kt) (pre-existing count-only prune tests)
|
||||
- [FileBuildResultRepositoryTest](../../src/test/kotlin/de/hoennig/werkator/build/FileBuildResultRepositoryTest.kt) (pre-existing count-only prune tests)
|
||||
|
||||
## The Solution
|
||||
|
||||
|
||||
@@ -39,7 +39,7 @@ So that pull-request branches get their commit status verified as before.
|
||||
|
||||
##### Verified by
|
||||
|
||||
- [WatcherTest: "a branch requiring a pull request is only built when its head matches a pull-request head"](../../src/test/kotlin/de/hoennig/gittally/watcher/WatcherTest.kt)
|
||||
- [WatcherTest: "a branch requiring a pull request is only built when its head matches a pull-request head"](../../src/test/kotlin/de/hoennig/werkator/watcher/WatcherTest.kt)
|
||||
|
||||
#### Scenario#000.02: A gated branch without a pull request is not built!
|
||||
|
||||
@@ -54,7 +54,7 @@ So that work-in-progress branches do not consume build capacity.
|
||||
|
||||
##### Verified by
|
||||
|
||||
- [WatcherTest: "a branch requiring a pull request is only built when its head matches a pull-request head"](../../src/test/kotlin/de/hoennig/gittally/watcher/WatcherTest.kt)
|
||||
- [WatcherTest: "a branch requiring a pull request is only built when its head matches a pull-request head"](../../src/test/kotlin/de/hoennig/werkator/watcher/WatcherTest.kt)
|
||||
|
||||
#### Scenario#000.03: Pull-request detection works without an API token!
|
||||
|
||||
@@ -66,7 +66,7 @@ So that GitTally needs no Gitea credentials for this feature.
|
||||
|
||||
##### Verified by
|
||||
|
||||
- [GitServiceTest: "pullRequestHeads returns the head commits of the remote's pull-request refs"](../../src/test/kotlin/de/hoennig/gittally/git/GitServiceTest.kt)
|
||||
- [GitServiceTest: "pullRequestHeads returns the head commits of the remote's pull-request refs"](../../src/test/kotlin/de/hoennig/werkator/git/GitServiceTest.kt)
|
||||
|
||||
#### Scenario#000.04: Ungated setups make no extra remote calls!
|
||||
|
||||
@@ -78,7 +78,7 @@ So that existing installations see no new network traffic.
|
||||
|
||||
##### Verified by
|
||||
|
||||
- [WatcherTest: "pull-request refs are not queried when no due branch requires a pull request"](../../src/test/kotlin/de/hoennig/gittally/watcher/WatcherTest.kt)
|
||||
- [WatcherTest: "pull-request refs are not queried when no due branch requires a pull request"](../../src/test/kotlin/de/hoennig/werkator/watcher/WatcherTest.kt)
|
||||
|
||||
#### Scenario#000.05: A branch entry overrides the default!
|
||||
|
||||
@@ -91,7 +91,7 @@ So that permanent branches like `main` keep building after merges, whose merge c
|
||||
|
||||
##### Verified by
|
||||
|
||||
- [WatcherTest: "a branch entry overrides requirePullRequest from the default entry"](../../src/test/kotlin/de/hoennig/gittally/watcher/WatcherTest.kt)
|
||||
- [WatcherTest: "a branch entry overrides requirePullRequest from the default entry"](../../src/test/kotlin/de/hoennig/werkator/watcher/WatcherTest.kt)
|
||||
|
||||
#### Scenario#000.06: Auto builds respect the gate!
|
||||
|
||||
@@ -105,7 +105,7 @@ So that scheduled rebuilds follow the same policy as push-triggered builds.
|
||||
|
||||
##### Verified by
|
||||
|
||||
- [WatcherTest: "an auto build requiring a pull request is skipped and its slot stays untriggered"](../../src/test/kotlin/de/hoennig/gittally/watcher/WatcherTest.kt)
|
||||
- [WatcherTest: "an auto build requiring a pull request is skipped and its slot stays untriggered"](../../src/test/kotlin/de/hoennig/werkator/watcher/WatcherTest.kt)
|
||||
|
||||
#### Scenario#000.07: The gate can be disabled globally for plain git origins!
|
||||
|
||||
@@ -119,7 +119,7 @@ So that the same committed configuration works on environments whose origin is p
|
||||
|
||||
##### Verified by
|
||||
|
||||
- [WatcherTest: "a disabled pull-request gate builds gated branches on plain-git origins without querying pull-request refs"](../../src/test/kotlin/de/hoennig/gittally/watcher/WatcherTest.kt)
|
||||
- [WatcherTest: "a disabled pull-request gate builds gated branches on plain-git origins without querying pull-request refs"](../../src/test/kotlin/de/hoennig/werkator/watcher/WatcherTest.kt)
|
||||
|
||||
## The Solution
|
||||
|
||||
|
||||
@@ -34,8 +34,8 @@ So that links in READMEs, wikis, and bookmarks stay valid across new builds.
|
||||
|
||||
##### Verified by
|
||||
|
||||
- [ArtifactFileControllerTest](../../src/test/kotlin/de/hoennig/gittally/server/ArtifactFileControllerTest.kt)
|
||||
- [BranchPermalinksTest](../../src/test/kotlin/de/hoennig/gittally/server/BranchPermalinksTest.kt)
|
||||
- [ArtifactFileControllerTest](../../src/test/kotlin/de/hoennig/werkator/server/ArtifactFileControllerTest.kt)
|
||||
- [BranchPermalinksTest](../../src/test/kotlin/de/hoennig/werkator/server/BranchPermalinksTest.kt)
|
||||
|
||||
#### Scenario#000.02: Directory URLs serve their index page like a static web server
|
||||
|
||||
@@ -49,7 +49,7 @@ So that legacy-style report links such as `/branches/main/reports/build/doc/` wo
|
||||
|
||||
##### Verified by
|
||||
|
||||
- [ArtifactFileControllerTest](../../src/test/kotlin/de/hoennig/gittally/server/ArtifactFileControllerTest.kt)
|
||||
- [ArtifactFileControllerTest](../../src/test/kotlin/de/hoennig/werkator/server/ArtifactFileControllerTest.kt)
|
||||
|
||||
#### Scenario#000.03: The bare permanent URL renders a permanent artifact index
|
||||
|
||||
@@ -63,8 +63,8 @@ So that users can browse the latest green artifacts from one stable bookmark.
|
||||
|
||||
##### Verified by
|
||||
|
||||
- [UiControllerTest](../../src/test/kotlin/de/hoennig/gittally/server/UiControllerTest.kt)
|
||||
- [PermanentBranchRoutesTest](../../src/test/kotlin/de/hoennig/gittally/server/PermanentBranchRoutesTest.kt) (the `/branches`, `/branches/<key>`, and `/branches/<key>/<path>` routes coexist)
|
||||
- [UiControllerTest](../../src/test/kotlin/de/hoennig/werkator/server/UiControllerTest.kt)
|
||||
- [PermanentBranchRoutesTest](../../src/test/kotlin/de/hoennig/werkator/server/PermanentBranchRoutesTest.kt) (the `/branches`, `/branches/<key>`, and `/branches/<key>/<path>` routes coexist)
|
||||
|
||||
#### Scenario#000.04: Green-only and unambiguous resolution
|
||||
|
||||
@@ -80,7 +80,7 @@ So that a permanent link never points at broken artifacts or the wrong branch.
|
||||
|
||||
##### Verified by
|
||||
|
||||
- [BranchPermalinksTest](../../src/test/kotlin/de/hoennig/gittally/server/BranchPermalinksTest.kt)
|
||||
- [BranchPermalinksTest](../../src/test/kotlin/de/hoennig/werkator/server/BranchPermalinksTest.kt)
|
||||
|
||||
#### Scenario#000.05: The latest green build survives pruning
|
||||
|
||||
@@ -94,8 +94,8 @@ So that a permanent link stays valid while newer builds fail, as long as the bra
|
||||
|
||||
##### Verified by
|
||||
|
||||
- [FileBuildResultRepositoryTest](../../src/test/kotlin/de/hoennig/gittally/build/FileBuildResultRepositoryTest.kt)
|
||||
- [WatcherTest](../../src/test/kotlin/de/hoennig/gittally/watcher/WatcherTest.kt)
|
||||
- [FileBuildResultRepositoryTest](../../src/test/kotlin/de/hoennig/werkator/build/FileBuildResultRepositoryTest.kt)
|
||||
- [WatcherTest](../../src/test/kotlin/de/hoennig/werkator/watcher/WatcherTest.kt)
|
||||
|
||||
#### Scenario#000.06: The branches view links the permanent URL
|
||||
|
||||
@@ -108,8 +108,8 @@ So that users can discover the permanent link without constructing it by hand.
|
||||
|
||||
##### Verified by
|
||||
|
||||
- [BranchListingTest](../../src/test/kotlin/de/hoennig/gittally/server/BranchListingTest.kt)
|
||||
- [UiControllerTest](../../src/test/kotlin/de/hoennig/gittally/server/UiControllerTest.kt)
|
||||
- [BranchListingTest](../../src/test/kotlin/de/hoennig/werkator/server/BranchListingTest.kt)
|
||||
- [UiControllerTest](../../src/test/kotlin/de/hoennig/werkator/server/UiControllerTest.kt)
|
||||
|
||||
## The Solution
|
||||
|
||||
|
||||
@@ -42,8 +42,8 @@ Each item is a TODO with the background that justifies it.
|
||||
|
||||
#### TODO 1 — Restrict the Gitea-token config file to the owner at creation
|
||||
|
||||
- [x] In [`InitCommand.kt:86-106`](../../src/main/kotlin/de/hoennig/gittally/commands/InitCommand.kt), create `.git/gittally/.gittally.yml` and its parent `.git/gittally/` with `0600`/`0700`, atomically at creation (as [`GitAskPass`](../../src/main/kotlin/de/hoennig/gittally/git/GitAskPass.kt) does), not via plain `writeText` at the umask default.
|
||||
**Done:** both `init` paths now go through [`SecretFiles`](../../src/main/kotlin/de/hoennig/gittally/SecretFiles.kt), which sets the mode as a file attribute at creation.
|
||||
- [x] In [`InitCommand.kt:86-106`](../../src/main/kotlin/de/hoennig/werkator/commands/InitCommand.kt), create `.git/gittally/.gittally.yml` and its parent `.git/gittally/` with `0600`/`0700`, atomically at creation (as [`GitAskPass`](../../src/main/kotlin/de/hoennig/werkator/git/GitAskPass.kt) does), not via plain `writeText` at the umask default.
|
||||
**Done:** both `init` paths now go through [`SecretFiles`](../../src/main/kotlin/de/hoennig/werkator/SecretFiles.kt), which sets the mode as a file attribute at creation.
|
||||
|
||||
**Background.**
|
||||
`init` creates the file it labels "secrets" — where the operator pastes the Gitea API token — with `writeText` and no permission restriction, so it inherits the umask (typically `0644`, world-readable).
|
||||
@@ -52,7 +52,7 @@ On a shared host (Hostsharing is a multi-tenant deployment target, per ADR 0005)
|
||||
|
||||
#### TODO 2 — Stop handing the control token to every unauthenticated reader
|
||||
|
||||
- [x] Reconsider the token distribution in [`UiController.kt:186`](../../src/main/kotlin/de/hoennig/gittally/server/UiController.kt) and [`fragments.html:9`](../../src/main/resources/templates/fragments.html): do not embed the live token in public HTML, or gate the pages behind the same check as the mutations.
|
||||
- [x] Reconsider the token distribution in [`UiController.kt:186`](../../src/main/kotlin/de/hoennig/werkator/server/UiController.kt) and [`fragments.html:9`](../../src/main/resources/templates/fragments.html): do not embed the live token in public HTML, or gate the pages behind the same check as the mutations.
|
||||
**Done in v0.9.10, without gating the pages.** Public read access is a requirement, not an oversight: build states, logs and artifacts must stay linkable without a login.
|
||||
So the `<meta>` tag is gone and `gittally.js` keeps the token in `localStorage`, asking for it once per browser (the operator reads it from `.git/gittally/control-token`, which needs shell access to the host).
|
||||
The token is a real secret again, and as a request header it stays inherently CSRF-safe — a foreign origin cannot set it without a CORS grant.
|
||||
@@ -61,7 +61,7 @@ On a shared host (Hostsharing is a multi-tenant deployment target, per ADR 0005)
|
||||
Superseded: read access no longer implies write access. `docs/deployment.md` gained a "Control Token" section describing the split.
|
||||
|
||||
**Background.**
|
||||
Every server-rendered page embeds the live control token in `<meta name="gittally-control-token">` so [`gittally.js`](../../src/main/resources/static/gittally.js) can read it, but no GET is authenticated.
|
||||
Every server-rendered page embeds the live control token in `<meta name="gittally-control-token">` so [`gittally.js`](../../src/main/resources/static/werkator.js) can read it, but no GET is authenticated.
|
||||
So `curl -s http://host:18080/ | grep gittally-control-token` yields the token, which unlocks restart/cancel/delete.
|
||||
Read access therefore equals write access, and the token provides no real second trust tier.
|
||||
Blast radius is limited to build-lifecycle operations (a DoS/integrity concern, not secret disclosure or RCE), which is why this is a design flaw rather than Critical — but the token gives a false sense of protection.
|
||||
@@ -70,7 +70,7 @@ Blast radius is limited to build-lifecycle operations (a DoS/integrity concern,
|
||||
|
||||
#### TODO 3 — Accept the control token via header only
|
||||
|
||||
- [x] Remove the `token` query-parameter variant from the three mutating endpoints in [`BuildsApiController.kt:90,115,129`](../../src/main/kotlin/de/hoennig/gittally/server/BuildsApiController.kt); keep only the `X-GitTally-Token` header (which the bundled UI already uses).
|
||||
- [x] Remove the `token` query-parameter variant from the three mutating endpoints in [`BuildsApiController.kt:90,115,129`](../../src/main/kotlin/de/hoennig/werkator/server/BuildsApiController.kt); keep only the `X-GitTally-Token` header (which the bundled UI already uses).
|
||||
|
||||
**Background.**
|
||||
Tokens in URLs are routinely written to access logs, reverse-proxy logs, browser history, and the `Referer` header on outbound navigation.
|
||||
@@ -79,7 +79,7 @@ The query-param path exists only for legacy convenience.
|
||||
|
||||
#### TODO 4 — Redact the Gitea token in `config:print`
|
||||
|
||||
- [x] Mask `git.token` (and any future secret) by default in [`ConfigPrintCommand.kt:20-31`](../../src/main/kotlin/de/hoennig/gittally/commands/ConfigPrintCommand.kt); gate the plaintext value behind an explicit `--show-secrets` flag.
|
||||
- [x] Mask `git.token` (and any future secret) by default in [`ConfigPrintCommand.kt:20-31`](../../src/main/kotlin/de/hoennig/werkator/commands/ConfigPrintCommand.kt); gate the plaintext value behind an explicit `--show-secrets` flag.
|
||||
Masked as `***` on both the `--full` and the raw path, with a leading YAML comment naming the flag, so the output stays parseable when piped.
|
||||
- [x] Update `tools/setup-gittally-instance:272`, which currently steers the operator to run `config:print --full` to view the token.
|
||||
|
||||
@@ -89,7 +89,7 @@ There is no redaction and no masked default.
|
||||
|
||||
#### TODO 5 — Reduce information disclosure on the unauthenticated read API
|
||||
|
||||
- [x] Decide whether build-log streaming ([`BuildsApiController`](../../src/main/kotlin/de/hoennig/gittally/server/BuildsApiController.kt) `/api/builds/current/{key}/log`), [`SystemApiController`](../../src/main/kotlin/de/hoennig/gittally/server/SystemApiController.kt), and [`WatcherApiController`](../../src/main/kotlin/de/hoennig/gittally/server/WatcherApiController.kt) should stay fully public, or be gated / scrubbed.
|
||||
- [x] Decide whether build-log streaming ([`BuildsApiController`](../../src/main/kotlin/de/hoennig/werkator/server/BuildsApiController.kt) `/api/builds/current/{key}/log`), [`SystemApiController`](../../src/main/kotlin/de/hoennig/werkator/server/SystemApiController.kt), and [`WatcherApiController`](../../src/main/kotlin/de/hoennig/werkator/server/WatcherApiController.kt) should stay fully public, or be gated / scrubbed.
|
||||
**Decided: they stay fully public, no scrubbing.** The watched projects (GitTally itself and hs.hsadmin.ng) are open source, the repositories hold no secrets, and the builds run tests against test data — credentials appearing in a log are fixtures, not real ones. Builds neither deploy nor sign; the only planned artifact is a jar.
|
||||
Public logs are also the point of the tool: a red build must be diagnosable from the link in the Gitea status without a login.
|
||||
This is a property of the watched project, not of GitTally: an installation whose builds touch real credentials must keep its instance off the public internet (reverse proxy or `bindAddress: 127.0.0.1`), because GitTally offers no per-endpoint gating.
|
||||
@@ -104,14 +104,14 @@ Raw build output may contain secrets echoed by build scripts; `/api/system` expo
|
||||
|
||||
A branch is built with its own build settings: `.gittally.yml` from the **build worktree** (the commit being built) overrides the `.git`/primary config — except for a pinned set that a branch must never control. **Implemented in this PR.**
|
||||
|
||||
- [x] Worktree config layer for builds via [`ConfigLoader.loadForWorktree`](../../src/main/kotlin/de/hoennig/gittally/config/ConfigLoader.kt), wired into the two build-time config consumers ([`BuildExecutor.branchConfig`](../../src/main/kotlin/de/hoennig/gittally/build/BuildExecutor.kt), [`FileArtifactStore.branchConfig`](../../src/main/kotlin/de/hoennig/gittally/artifacts/FileArtifactStore.kt)) — both already hold the prepared worktree path. Precedence is worktree > `.git` > project.
|
||||
- [x] Worktree config layer for builds via [`ConfigLoader.loadForWorktree`](../../src/main/kotlin/de/hoennig/werkator/config/ConfigLoader.kt), wired into the two build-time config consumers ([`BuildExecutor.branchConfig`](../../src/main/kotlin/de/hoennig/werkator/build/BuildExecutor.kt), [`FileArtifactStore.branchConfig`](../../src/main/kotlin/de/hoennig/werkator/artifacts/FileArtifactStore.kt)) — both already hold the prepared worktree path. Precedence is worktree > `.git` > project.
|
||||
- [x] **Pinned to `.git`/primary — stripped from the worktree layer:** `git`, `gitea`, `server` (secrets + server-side), and the sandbox policy `docker.enabled`/`docker.network`. A branch cannot disable its container or change its network mode.
|
||||
- [x] Worktree-overridable: `buildCommand`, `cleanCommand`, `artifactDirs`, `stdoutLog`/`stderrLog`, `autoBuild`, and `docker.image`/`dockerfile`/`context`/`env`.
|
||||
- [x] Pinned set enforced in code (`ConfigLoader.stripPinned`), documented in `docs/configuration.md`, and asserted as an invariant in `AGENTS.md`.
|
||||
- [ ] **Deferred:** `autoBuild` scheduling and `requirePullRequest` are still read from the primary config, not the worktree — the watcher evaluates them *before* a build (and thus a worktree) exists. Sourcing them per-branch would need the watcher to read the branch's committed config directly (e.g. via `git show <branch>:.gittally.yml`); out of scope here.
|
||||
|
||||
**Background.**
|
||||
The build command is executed via `bash -c "$3"` inside the build container ([`DockerBuildRunner.kt:285`](../../src/main/kotlin/de/hoennig/gittally/build/DockerBuildRunner.kt)).
|
||||
The build command is executed via `bash -c "$3"` inside the build container ([`DockerBuildRunner.kt:285`](../../src/main/kotlin/de/hoennig/werkator/build/DockerBuildRunner.kt)).
|
||||
Letting a branch define its own `buildCommand` is not a new risk — a CI already runs arbitrary code from that commit; the container is the sandbox.
|
||||
The real escalation is a branch turning the sandbox **off**: if the worktree could set `docker.enabled: false` (or host `docker.network`), the build would run natively on the host — which is why those two keys are pinned.
|
||||
Secrets are also safe from the build process (the Gitea token is used only by the server/watcher and is never placed in the build environment — `runCommand` passes only `mapOf("branch" to ...)`), and the whole `git`/`gitea`/`server` sections are stripped from the worktree layer as defense in depth.
|
||||
@@ -121,7 +121,7 @@ Before this PR all build config was loaded from the primary checkout via `config
|
||||
|
||||
#### TODO 7 — Default `bindAddress` to `127.0.0.1`
|
||||
|
||||
- [x] Change the default in [`GitTallyConfig.kt:21`](../../src/main/kotlin/de/hoennig/gittally/config/GitTallyConfig.kt) and the `init` template ([`InitCommand.kt:126`](../../src/main/kotlin/de/hoennig/gittally/commands/InitCommand.kt)) from `0.0.0.0` to `127.0.0.1`; require operators to opt into all-interfaces.
|
||||
- [x] Change the default in [`GitTallyConfig.kt:21`](../../src/main/kotlin/de/hoennig/werkator/config/WerkatorConfig.kt) and the `init` template ([`InitCommand.kt:126`](../../src/main/kotlin/de/hoennig/werkator/commands/InitCommand.kt)) from `0.0.0.0` to `127.0.0.1`; require operators to opt into all-interfaces.
|
||||
Shipped as v0.9.9 with the migration note in the release notes, `docs/configuration.md` ("Notes on `server.bindAddress`") and `docs/deployment.md`: existing configs keep their explicit value, and the managed nginx now needs `0.0.0.0` set deliberately.
|
||||
|
||||
**Background.**
|
||||
@@ -130,7 +130,7 @@ The deployment doc already recommends `127.0.0.1`; the default and template shou
|
||||
|
||||
#### TODO 8 — Compare fixed-length hashes in the token check
|
||||
|
||||
- [x] In [`ControlTokenService.kt:35-37`](../../src/main/kotlin/de/hoennig/gittally/server/ControlTokenService.kt), compare `SHA-256(submitted)` against `SHA-256(secret)` with `MessageDigest.isEqual`, so the comparison is always over equal-length buffers.
|
||||
- [x] In [`ControlTokenService.kt:35-37`](../../src/main/kotlin/de/hoennig/werkator/server/ControlTokenService.kt), compare `SHA-256(submitted)` against `SHA-256(secret)` with `MessageDigest.isEqual`, so the comparison is always over equal-length buffers.
|
||||
|
||||
**Background.**
|
||||
`MessageDigest.isEqual` returns early on a length mismatch, leaking the token length via timing.
|
||||
@@ -138,7 +138,7 @@ Largely theoretical given the 192-bit CSPRNG token, but a cheap deviation from c
|
||||
|
||||
#### TODO 9 — Add `--` before positional refnames in git calls
|
||||
|
||||
- [x] Insert `--` before the branch argument in `checkout`, `fetchBranch`, and `resetHardToOrigin` in [`GitService.kt:145,40,155`](../../src/main/kotlin/de/hoennig/gittally/git/GitService.kt) (e.g. `git switch -- <branch>`).
|
||||
- [x] Insert `--` before the branch argument in `checkout`, `fetchBranch`, and `resetHardToOrigin` in [`GitService.kt:145,40,155`](../../src/main/kotlin/de/hoennig/werkator/git/GitService.kt) (e.g. `git switch -- <branch>`).
|
||||
**Done for `checkout` and `fetchBranch`.** `resetHardToOrigin` keeps its plain form: `git reset --hard -- <commit>` is rejected (`fatal: Cannot do hard reset with paths`), and its argument is already prefixed with `origin/`, so it can never start with `-`.
|
||||
|
||||
**Background.**
|
||||
@@ -147,8 +147,8 @@ These three methods currently have no production callers and the actively-used p
|
||||
|
||||
#### TODO 10 — Create secret files restricted atomically
|
||||
|
||||
- [x] Set the mode at creation for the control-token file ([`ControlTokenService.kt:29-30`](../../src/main/kotlin/de/hoennig/gittally/server/ControlTokenService.kt)) and the setup-script YAML (`tools/setup-gittally-instance:253`), instead of `chmod 0600` after the write.
|
||||
**Done:** the control-token file via [`SecretFiles`](../../src/main/kotlin/de/hoennig/gittally/SecretFiles.kt), the setup script by writing the YAML in a `umask 077` subshell instead of `chmod`-ing afterwards.
|
||||
- [x] Set the mode at creation for the control-token file ([`ControlTokenService.kt:29-30`](../../src/main/kotlin/de/hoennig/werkator/server/ControlTokenService.kt)) and the setup-script YAML (`tools/setup-gittally-instance:253`), instead of `chmod 0600` after the write.
|
||||
**Done:** the control-token file via [`SecretFiles`](../../src/main/kotlin/de/hoennig/werkator/SecretFiles.kt), the setup script by writing the YAML in a `umask 077` subshell instead of `chmod`-ing afterwards.
|
||||
|
||||
**Background.**
|
||||
Both currently write the file at the umask default and tighten it afterward, leaving a brief window where the secret exists world-readable.
|
||||
@@ -175,11 +175,11 @@ A small TOCTOU gap; `GitAskPass`'s atomic-at-creation approach is the pattern to
|
||||
|
||||
Recorded so future changes do not silently regress these.
|
||||
|
||||
- **Path traversal in artifact serving** — [`ArtifactFileController`](../../src/main/kotlin/de/hoennig/gittally/server/ArtifactFileController.kt) normalizes then enforces `startsWith(artifactDir)` and `isRegularFile(..., NOFOLLOW_LINKS)` (rejects symlink escape); [`FileArtifactStore`](../../src/main/kotlin/de/hoennig/gittally/artifacts/FileArtifactStore.kt) whitelists the key to `[A-Za-z0-9._-]+` and requires `dir.parent == branchesDir`.
|
||||
- **Command injection** — every git/docker/certbot/nginx call uses `ProcessBuilder(List<String>)` ([`GitCommandRunner.kt`](../../src/main/kotlin/de/hoennig/gittally/git/GitCommandRunner.kt)); no `Runtime.exec(String)`, no shell-string interpolation; the only `sh -c`/`bash -c` uses pass data as positional args.
|
||||
- **Branch-name → filesystem** — always routed through [`ArtifactKeys.sanitize`](../../src/main/kotlin/de/hoennig/gittally/build/ArtifactKeys.kt) (`/` → `_`) plus a SHA suffix, so worktree/container/volume names cannot traverse.
|
||||
- **Path traversal in artifact serving** — [`ArtifactFileController`](../../src/main/kotlin/de/hoennig/werkator/server/ArtifactFileController.kt) normalizes then enforces `startsWith(artifactDir)` and `isRegularFile(..., NOFOLLOW_LINKS)` (rejects symlink escape); [`FileArtifactStore`](../../src/main/kotlin/de/hoennig/werkator/artifacts/FileArtifactStore.kt) whitelists the key to `[A-Za-z0-9._-]+` and requires `dir.parent == branchesDir`.
|
||||
- **Command injection** — every git/docker/certbot/nginx call uses `ProcessBuilder(List<String>)` ([`GitCommandRunner.kt`](../../src/main/kotlin/de/hoennig/werkator/git/GitCommandRunner.kt)); no `Runtime.exec(String)`, no shell-string interpolation; the only `sh -c`/`bash -c` uses pass data as positional args.
|
||||
- **Branch-name → filesystem** — always routed through [`ArtifactKeys.sanitize`](../../src/main/kotlin/de/hoennig/werkator/build/ArtifactKeys.kt) (`/` → `_`) plus a SHA suffix, so worktree/container/volume names cannot traverse.
|
||||
- **XSS** — no `th:utext` in any template; `gittally.js` builds all DOM via `createElement` + `textContent`/`dataset`, no `innerHTML`.
|
||||
- **SSRF** — the Gitea status proxy validates the commit against `[0-9a-fA-F]{7,40}` ([`StatusApiController.kt`](../../src/main/kotlin/de/hoennig/gittally/server/StatusApiController.kt)); the Gitea base URL/owner/repo/token come from config, not the request.
|
||||
- **SSRF** — the Gitea status proxy validates the commit against `[0-9a-fA-F]{7,40}` ([`StatusApiController.kt`](../../src/main/kotlin/de/hoennig/werkator/server/StatusApiController.kt)); the Gitea base URL/owner/repo/token come from config, not the request.
|
||||
- **Deserialization** — Jackson JSON/YAML without polymorphic/default typing (no gadget-chain RCE); unreadable state files degrade to empty.
|
||||
- **Credential transport** — Gitea token sent as an `Authorization` header, never in a URL ([`GiteaClient.kt`](../../src/main/kotlin/de/hoennig/gittally/gitea/GiteaClient.kt)); git auth via env-based `GIT_ASKPASS` with a `0700` script containing no secrets, deleted in `finally`; TLS verification never disabled.
|
||||
- **nginx/certbot** — `serverName`/`upstreamHost` validated against `[A-Za-z0-9][A-Za-z0-9.-]*` before substitution ([`NginxProxyManager.kt`](../../src/main/kotlin/de/hoennig/gittally/server/NginxProxyManager.kt)); ports range-checked.
|
||||
- **Credential transport** — Gitea token sent as an `Authorization` header, never in a URL ([`GiteaClient.kt`](../../src/main/kotlin/de/hoennig/werkator/gitea/GiteaClient.kt)); git auth via env-based `GIT_ASKPASS` with a `0700` script containing no secrets, deleted in `finally`; TLS verification never disabled.
|
||||
- **nginx/certbot** — `serverName`/`upstreamHost` validated against `[A-Za-z0-9][A-Za-z0-9.-]*` before substitution ([`NginxProxyManager.kt`](../../src/main/kotlin/de/hoennig/werkator/server/NginxProxyManager.kt)); ports range-checked.
|
||||
|
||||
@@ -35,8 +35,8 @@ So that critical load is visible at a glance.
|
||||
|
||||
##### Verified by
|
||||
|
||||
- [UiViewsTest — "utilization highlights warn from 80% and crit from 90% of the total"](../../src/test/kotlin/de/hoennig/gittally/server/UiViewsTest.kt)
|
||||
- [UiViewsTest — "only the used rows with a total get the critical highlighting"](../../src/test/kotlin/de/hoennig/gittally/server/UiViewsTest.kt)
|
||||
- [UiViewsTest — "utilization highlights warn from 80% and crit from 90% of the total"](../../src/test/kotlin/de/hoennig/werkator/server/UiViewsTest.kt)
|
||||
- [UiViewsTest — "only the used rows with a total get the critical highlighting"](../../src/test/kotlin/de/hoennig/werkator/server/UiViewsTest.kt)
|
||||
|
||||
#### Scenario#000.02: Unavailable metrics are never highlighted
|
||||
|
||||
@@ -48,7 +48,7 @@ So that hosts without `/proc` (no metrics, `n/a` cells) render unchanged.
|
||||
|
||||
##### Verified by
|
||||
|
||||
- [UiViewsTest — "utilization highlighting is off when a value or the total is unavailable"](../../src/test/kotlin/de/hoennig/gittally/server/UiViewsTest.kt)
|
||||
- [UiViewsTest — "utilization highlighting is off when a value or the total is unavailable"](../../src/test/kotlin/de/hoennig/werkator/server/UiViewsTest.kt)
|
||||
|
||||
## The Solution
|
||||
|
||||
|
||||
@@ -37,7 +37,7 @@ So that a service restart never loses a build or marks its commit as failed.
|
||||
|
||||
##### Verified by
|
||||
|
||||
- [BuildExecutorTest — "shutdown kills an executing build and records INTERRUPTED, not FAILED"](../../src/test/kotlin/de/hoennig/gittally/build/BuildExecutorTest.kt)
|
||||
- [BuildExecutorTest — "shutdown kills an executing build and records INTERRUPTED, not FAILED"](../../src/test/kotlin/de/hoennig/werkator/build/BuildExecutorTest.kt)
|
||||
|
||||
#### Scenario#000.02: A queued build stays PENDING over a shutdown
|
||||
|
||||
@@ -50,7 +50,7 @@ So that queued builds survive a restart the same way executing builds do.
|
||||
|
||||
##### Verified by
|
||||
|
||||
- [BuildExecutorTest — "a build still queued at shutdown stays PENDING for the startup recovery"](../../src/test/kotlin/de/hoennig/gittally/build/BuildExecutorTest.kt)
|
||||
- [BuildExecutorTest — "a build still queued at shutdown stays PENDING for the startup recovery"](../../src/test/kotlin/de/hoennig/werkator/build/BuildExecutorTest.kt)
|
||||
|
||||
#### Scenario#000.03: No failure status is posted to Gitea for an interrupted build
|
||||
|
||||
@@ -63,8 +63,8 @@ So that a commit does not turn red because of a service restart.
|
||||
|
||||
##### Verified by
|
||||
|
||||
- [GiteaStateMappingTest](../../src/test/kotlin/de/hoennig/gittally/gitea/GiteaStateMappingTest.kt)
|
||||
- [GiteaClientTest — "maps every build status to the documented Gitea state"](../../src/test/kotlin/de/hoennig/gittally/gitea/GiteaClientTest.kt)
|
||||
- [GiteaStateMappingTest](../../src/test/kotlin/de/hoennig/werkator/gitea/GiteaStateMappingTest.kt)
|
||||
- [GiteaClientTest — "maps every build status to the documented Gitea state"](../../src/test/kotlin/de/hoennig/werkator/gitea/GiteaClientTest.kt)
|
||||
|
||||
## The Solution
|
||||
|
||||
|
||||
@@ -34,7 +34,7 @@ So that the cleanup is part of every GitTally installation instead of a manual s
|
||||
|
||||
##### Verified by
|
||||
|
||||
- [InitCommandTest — "--systemd also generates the nightly Docker cleanup timer"](../../src/test/kotlin/de/hoennig/gittally/commands/InitCommandTest.kt)
|
||||
- [InitCommandTest — "--systemd also generates the nightly Docker cleanup timer"](../../src/test/kotlin/de/hoennig/werkator/commands/InitCommandTest.kt)
|
||||
|
||||
#### Scenario#000.02: The cleanup prunes containers and images but never volumes
|
||||
|
||||
@@ -48,8 +48,8 @@ So that nightly builds start from fresh images while the Gradle caches survive.
|
||||
|
||||
##### Verified by
|
||||
|
||||
- [SystemdServiceFilesTest — "prune service cleans containers and images but never volumes"](../../src/test/kotlin/de/hoennig/gittally/commands/SystemdServiceFilesTest.kt)
|
||||
- [SystemdServiceFilesTest — "prune timer fires nightly at 02:00 and catches up after downtime"](../../src/test/kotlin/de/hoennig/gittally/commands/SystemdServiceFilesTest.kt)
|
||||
- [SystemdServiceFilesTest — "prune service cleans containers and images but never volumes"](../../src/test/kotlin/de/hoennig/werkator/commands/SystemdServiceFilesTest.kt)
|
||||
- [SystemdServiceFilesTest — "prune timer fires nightly at 02:00 and catches up after downtime"](../../src/test/kotlin/de/hoennig/werkator/commands/SystemdServiceFilesTest.kt)
|
||||
|
||||
## The Solution
|
||||
|
||||
|
||||
@@ -0,0 +1,189 @@
|
||||
> **WARNING:** This document describes only the change applied in this PR.
|
||||
> It may already be outdated once the next PR is merged.
|
||||
> Historic PR-documentation is not maintained along with new PRs — treat it as a snapshot, not as current documentation.
|
||||
|
||||
## The Problem
|
||||
|
||||
`gitTally` is the name of another product in the git space.
|
||||
Sharing it is a risk that is cheap to remove now and expensive to remove later, so the project is renamed to **Werkator** as a precaution.
|
||||
Nothing about what the build system does changes.
|
||||
|
||||
A rename of a CI system is not a search-and-replace, because the name is part of a running installation:
|
||||
|
||||
- The configuration is found by name — `.gittally.yml` and `.git/gittally/.gittally.yml`.
|
||||
- The state is found by path — `.git/gittally/` holds the build history, the control token, the scheduled-build state and the build worktrees.
|
||||
|
||||
Neither is loud when it goes missing.
|
||||
A configuration that is not found leaves every setting at its default, and a state directory that is not found is simply empty.
|
||||
An installation updated without renaming would therefore not fail; it would come up looking healthy, having forgotten its credentials, its addresses, its build history and what it builds.
|
||||
|
||||
The rename must therefore carry existing installations across, not just rename files in this repository.
|
||||
|
||||
## Non-Goals
|
||||
|
||||
- No behavioral change to builds, watching, the API or the web UI.
|
||||
- No rename in the old PR-docs under `docs/prs/` and no rewriting of the historic entries in the release notes: both record what was published at the time.
|
||||
- No automatic migration of anything outside the repository — the artifact root, the systemd units, the runtime bundle, the Docker names and labels and the Gitea check context stay manual, listed in [the migration plan](../werkator-migrationsplan.md).
|
||||
- No permanent dual-name support: the configuration fallback is temporary and goes away once the watched repositories have been renamed.
|
||||
|
||||
## The Scenarios
|
||||
|
||||
### Feature: an installation keeps working across the rename
|
||||
|
||||
#### Background
|
||||
|
||||
- The *committed configuration* is `.werkator.yml` at the repository root, in a build worktree, and as committed on a branch.
|
||||
- The *machine configuration* is `.git/werkator/.werkator.yml` and holds the secrets.
|
||||
- The *state directory* is `.git/werkator/` and holds everything the instance remembers.
|
||||
- *Pre-rename* names are spelled exactly as they were: `.gittally.yml` and `.git/gittally/`.
|
||||
|
||||
#### Scenario#1.01: A configuration under its pre-rename name is still read
|
||||
|
||||
So that an installation may be updated and renamed in two separate steps, at its own pace.
|
||||
|
||||
- **Given** a repository whose committed configuration is named `.gittally.yml`
|
||||
- **and** no `.werkator.yml` next to it
|
||||
- **When** the configuration is loaded
|
||||
- **Then** its settings take effect exactly as under the current name
|
||||
|
||||
##### Verified by
|
||||
|
||||
- [ConfigLoaderTest: "falls back to the pre-rename .gittally.yml at the repository root"](../../src/test/kotlin/de/hoennig/werkator/config/ConfigLoaderTest.kt)
|
||||
- [ConfigLoaderTest: "falls back to the pre-rename machine config under .git/gittally"](../../src/test/kotlin/de/hoennig/werkator/config/ConfigLoaderTest.kt)
|
||||
- [ConfigLoaderTest: "a branch whose config is committed under the pre-rename name is still read as the branch layer"](../../src/test/kotlin/de/hoennig/werkator/config/ConfigLoaderTest.kt)
|
||||
- [WatcherTest: "a branch config committed under the pre-rename name is still read"](../../src/test/kotlin/de/hoennig/werkator/watcher/WatcherTest.kt)
|
||||
|
||||
#### Scenario#1.02: The current name wins, and the old file is not merged
|
||||
|
||||
So that a half-done rename cannot revive a setting somebody deliberately dropped while rewriting.
|
||||
|
||||
- **Given** a repository holding both `.werkator.yml` and `.gittally.yml`
|
||||
- **When** the configuration is loaded
|
||||
- **Then** only `.werkator.yml` is read
|
||||
- **and** keys present only in `.gittally.yml` have no effect
|
||||
|
||||
##### Verified by
|
||||
|
||||
- [ConfigLoaderTest: "the current name wins where both exist, so a half-done rename is not merged"](../../src/test/kotlin/de/hoennig/werkator/config/ConfigLoaderTest.kt)
|
||||
|
||||
#### Scenario#1.03: The state directory moves itself at the first start
|
||||
|
||||
So that an update does not silently cost an installation its build history and its control token.
|
||||
|
||||
- **Given** an installation whose state lives in `.git/gittally/`
|
||||
- **and** no `.git/werkator/` next to it
|
||||
- **When** any Werkator command is started in that repository
|
||||
- **Then** the directory is `.git/werkator/` afterwards, with its contents
|
||||
- **and** the build history and the control token are the ones from before
|
||||
|
||||
##### Verified by
|
||||
|
||||
- [StateDirMigrationTest: "moves the pre-rename state directory to its current path"](../../src/test/kotlin/de/hoennig/werkator/StateDirMigrationTest.kt)
|
||||
|
||||
#### Scenario#1.04: The moved worktrees are dropped rather than repaired
|
||||
|
||||
So that a build worktree pointing at its old path cannot break the next build.
|
||||
|
||||
- **Given** a state directory that is moved and holds build worktrees
|
||||
- **When** the move happens
|
||||
- **Then** the worktrees are gone
|
||||
- **and** the rest of the state survives
|
||||
- **and** the next build of a branch recreates its worktree
|
||||
|
||||
##### Verified by
|
||||
|
||||
- [StateDirMigrationTest: "drops the moved worktrees, because they point at their old path"](../../src/test/kotlin/de/hoennig/werkator/StateDirMigrationTest.kt)
|
||||
|
||||
#### Scenario#1.05: Two state directories are never merged or guessed between
|
||||
|
||||
So that an operator who moved the directory by hand does not lose the live state to an automatism.
|
||||
|
||||
- **Given** an installation holding both `.git/gittally/` and `.git/werkator/`
|
||||
- **When** a command is started
|
||||
- **Then** nothing is moved
|
||||
- **and** a warning names the leftover
|
||||
|
||||
##### Verified by
|
||||
|
||||
- [StateDirMigrationTest: "leaves both alone when the current directory already exists"](../../src/test/kotlin/de/hoennig/werkator/StateDirMigrationTest.kt)
|
||||
- [StateDirMigrationTest: "does nothing where there is no pre-rename directory"](../../src/test/kotlin/de/hoennig/werkator/StateDirMigrationTest.kt)
|
||||
|
||||
#### Scenario#1.06: The machine configuration survives a directory that moved without it
|
||||
|
||||
So that the move cannot produce a pair of names its own lookup does not expect.
|
||||
|
||||
- **Given** a state directory that has moved to `.git/werkator/`
|
||||
- **and** the machine configuration inside it still named `.gittally.yml`
|
||||
- **When** the configuration is loaded
|
||||
- **Then** its settings take effect
|
||||
- **and** where the move did it, the file carries the current name afterwards
|
||||
|
||||
##### Verified by
|
||||
|
||||
- [StateDirMigrationTest: "renames the machine configuration inside the moved directory"](../../src/test/kotlin/de/hoennig/werkator/StateDirMigrationTest.kt)
|
||||
- [StateDirMigrationTest: "never overwrites a machine configuration that already carries the current name"](../../src/test/kotlin/de/hoennig/werkator/StateDirMigrationTest.kt)
|
||||
- [ConfigLoaderTest: "finds the machine config left under its old name in an already-moved directory"](../../src/test/kotlin/de/hoennig/werkator/config/ConfigLoaderTest.kt)
|
||||
|
||||
## The Solution
|
||||
|
||||
**One spelling rule.**
|
||||
`Werkator` where the name is prose, capitalized where it is a Kotlin type and the file holding it, lowercase everywhere a machine reads it — the command, the packages, paths, configuration keys and values, the Gitea check context.
|
||||
Environment variables keep their own convention and are uppercase throughout.
|
||||
This is what turns a rename into a decidable question instead of a matter of taste, and it is applied across the whole repository, file names included.
|
||||
|
||||
**A name fallback for the configuration, in one place.**
|
||||
[`ConfigFiles`](../../src/main/kotlin/de/hoennig/werkator/config/ConfigFiles.kt) holds the pair of names and is used by all four lookups: the machine and project layers in `ConfigLoader.loadRaw`, the build worktree in `ConfigLoader.loadForWorktree`, the branch layer the watcher reads out of git, and the same read in the web UI.
|
||||
The current name wins and the old file is then ignored rather than merged — two files side by side are a half-done rename, not a layering.
|
||||
Error messages name the file that was actually read, so they never point at a file that does not exist.
|
||||
|
||||
**A move that finishes the job.**
|
||||
The deployment to vm4006 found the gap the hard way: the move renames the *directory* and leaves the file inside it alone, so the machine configuration ended up at `.git/werkator/.gittally.yml` — a pair of names the lookup did not expect.
|
||||
The instance came up with empty credentials and no host build definitions, without an error, which is the failure this PR exists to prevent.
|
||||
`StateDirMigration` now renames the configuration along with the directory, unless one under the current name is already there, and `ConfigFiles` carries the intermediate path as a third candidate for a directory somebody moved by hand.
|
||||
|
||||
The same deployment found the second half of it: `init --systemd` runs `init`, whose "does it already exist" check knew only the current name, so it wrote a fresh template `.werkator.yml` beside the repository's committed `.gittally.yml` — and the current name wins, so the repository would have started building the template's `./gradlew test` instead of what it says it builds.
|
||||
Both checks now ask `ConfigFiles`, which is the same question the loader asks.
|
||||
|
||||
**A one-time move for the state.**
|
||||
[`StateDirMigration`](../../src/main/kotlin/de/hoennig/werkator/StateDirMigration.kt) renames `.git/gittally` to `.git/werkator` from `CliRunner`, before any command resolves a path under it and therefore before the second Spring context of `server` exists.
|
||||
A fallback was rejected here: unlike a configuration, the state is written, so a fallback would have to decide on every write which of two directories wins, where a one-time move decides once and leaves a single path behind.
|
||||
The move is deliberately narrow — only when the old directory exists and the new one does not — and a failure is an error in the log, never an abort, because a CI must not hang on it.
|
||||
|
||||
**A round number for the new name.**
|
||||
The release after `0.9.21` is `1.0.0`, and the release note says why: a product that changes its name is better off counting from one under it.
|
||||
It is deliberately not a claim about maturity — plan steps 14, 17 and 18 are open.
|
||||
|
||||
**A plan for what cannot be automated.**
|
||||
[`docs/werkator-migrationsplan.md`](../werkator-migrationsplan.md) lists the artifact root, the systemd units, the Docker names and labels, the runtime bundle, the managed nginx container and the Gitea check context, with the order of work, the verification and the rollback.
|
||||
The rollback section names the asymmetry: the new version reads both names, the old one only the old, so a rollback works only while the configuration files still carry their pre-rename names.
|
||||
|
||||
## Open Questions
|
||||
|
||||
- **Decided: lowercase.** The default `gitea.statusContext` is `werkator`.
|
||||
It was worth asking, because it is the one value a human reads as a label, in Gitea next to the commit.
|
||||
It stays lowercase because it is also matched by Gitea and read back by the client, which makes it a value, not prose.
|
||||
|
||||
## Additional Changes
|
||||
|
||||
- Deleted `docs/migration-from-legacy.md`.
|
||||
It mapped the legacy bash script's environment variables to YAML keys, and every host it addressed has migrated.
|
||||
Its removal also settles one open item of [plan step 18](../plan/18-remove-branches-section.md).
|
||||
- Fixed a broken web UI: five templates already referenced `/werkator.js` and `/werkator.css` while the static files were still named `gittally.*`, so every page but the release notes served neither stylesheet nor live updates.
|
||||
- Renamed the Kotlin types `werkatorCommand` and `werkatorMeta`, which a case-insensitive replace had left lowercase, and the constant `werkator_LABEL` to `WERKATOR_LABEL`.
|
||||
- Added the release-notes entry for the rename, as `unreleased`.
|
||||
- Removed the legacy environment-variable conversion from `tools/setup-werkator-instance`.
|
||||
The blanket rename had rewritten the old script's `GITTALLY_*` variables to a spelling that never existed on any host, so the conversion would have read nothing from a real legacy file and written an almost empty configuration — silently.
|
||||
The conversion has served its purpose with the vm2176 → vm4006 migration; what remains is the setup of a new instance: the preconditions, the credential prompt, and the machine configuration written mode 600.
|
||||
It also stops emitting a legacy `branches:` section, which [plan step 18](../plan/18-remove-branches-section.md) is about to reject outright.
|
||||
- Restored the real `GITTALLY_*` spelling in `docs/plan/00-legacy-analysis.md` and `docs/plan/13-nginx-tls.md`, which record what the old script read.
|
||||
- Left the pre-rename fallback out of the release notes and `docs/configuration.md`.
|
||||
Exactly one repository carries the old names and it is migrated by hand in the same move as this release, so the fallback is a transition of days rather than something to plan around.
|
||||
It stays described where it is worked on: in `ConfigFiles`, in `StateDirMigration`, and in the migration plan.
|
||||
- Migrated this repository's own `.werkator.yml` from the deprecated `branches` section to a `builds.default` definition with a `trigger` block.
|
||||
Nothing about its build changes; it stops being the blocker for the precondition of [plan step 18](../plan/18-remove-branches-section.md), which requires that no configuration still in play carries the section, and which rejects it by name afterwards.
|
||||
|
||||
## Follow-up PRs
|
||||
|
||||
- Set the version and the release date, and deploy to vm4006 following the migration plan.
|
||||
- Change `gitea.statusContext` in the watched repository `hs.hsadmin.ng`, where `origin/master` still sets `GitTally`, together with the branch protection rule that names the check.
|
||||
- Remove the configuration name fallback once the watched repositories carry the current names, and reject a leftover `.gittally.yml` by name — the same reasoning as for the legacy `branches` section in [plan step 18](../plan/18-remove-branches-section.md).
|
||||
Reference in New Issue
Block a user