Files

T

mhoennig 729eea5e6c A build definition carries the whole build; branches is legacy

`builds` and the legacy `branches` are now either/or: `branches` is read
only while the merged configuration defines no build at all — a leftover
`builds.maxConcurrent` is not one — and ignored with a warning as soon as
one exists. Two half-answers to "what does this build run" would silently
pull against each other, and the committed configs still carrying both
must not change behaviour before they are migrated.

A definition therefore gained the settings it was missing:
`requirePullRequest` and `docker.enabled`/`network`. Those stay pinned —
`stripPinned` now removes them from a branch layer wherever they appear,
in a definition as well as in a legacy branch entry.

`builds.default` becomes the base every other definition inherits its
settings from, never its trigger: `onPush`, `atTimes`, `branches`, and
`activeWithin` say when and where *this* build runs. The inheritance is
applied after all layers are merged, which is what makes a build invented
on a branch inherit the host's sandbox policy instead of the data-class
default — otherwise a branch could get a native build past the pinning by
defining a job the host has never heard of.

Two bugs found on the way, both the same shape as the build command the
artifact page used to get wrong:

- `FileArtifactStore` read the artifact directories from the plain branch
  settings, so a job adding its own `artifactDirs` never had them stored.
  It goes through `GitTallyConfig.buildSettings` now, like everything else
  that asks what a build runs.
- `Watcher.definitionsFor` cached the per-branch definitions by head
  commit alone, so an edited machine or project config only took effect
  once the branch moved — on a quiet branch, never. The primary config is
  part of the cache key now.

2026-08-29 11:18:35 +02:00

6.3 KiB

Raw Blame History

Migration from the Legacy Script

The bash script legacy/gitTally is deprecated and replaced by this application. This document maps the legacy environment-variable configuration to the YAML configuration and lists the manual migration steps. See configuration.md for the full configuration reference and deployment.md for the new service setup.

Configuration Mapping

Legacy configuration came from environment variables (gitTally --env template, sourced env files). The new configuration lives in two YAML files: .gittally.yml (committed) and .git/gittally/.gittally.yml (machine-specific, secrets).

Build-level keys below live in a build definition under builds.<name>; use builds.default for what used to be the global value — it is the base every other definition inherits its settings from.

Legacy environment variable	New YAML key
`GITTALLY_BUILD_COMMAND`	`builds.<name>.buildCommand`
`GITTALLY_BUILD_CLEAN_COMMAND`	`builds.<name>.cleanCommand`
`GITTALLY_BUILD_ARTEFACT_DIRS`	`builds.<name>.artifactDirs` — YAML list instead of `;`-separated
`GITTALLY_BUILD_STDOUT_LOG`	`builds.<name>.stdoutLog`
`GITTALLY_BUILD_STDERR_LOG`	`builds.<name>.stderrLog`
`GITTALLY_NEW_BRANCH_COMMIT_MAX_AGE`	`watcher.newBranchMaxAge`
`GITTALLY_BUILD_DOCKER_IMAGE`	`builds.<name>.docker.image` — also set `docker.enabled: true` (replaces the `--docker` flag)
`GITTALLY_BUILD_DOCKERFILE`	`builds.<name>.docker.dockerfile`
`GITTALLY_BUILD_DOCKER_CONTEXT`	`builds.<name>.docker.context`
`GITTALLY_BUILD_DOCKER_NETWORK`	`builds.<name>.docker.network` — default is now Docker's default network, not `host`
`GITTALLY_BUILD_DOCKER_ENV`	`builds.<name>.docker.env` — YAML map instead of space-separated assignments
`GITTALLY_ARTIFACT_SERVER_PORT`	`server.port`
`GITTALLY_ARTIFACT_SERVER_BIND_ADDRESS`	`server.bindAddress`
`GITTALLY_ARTIFACT_PUBLIC_BASE_URL`	`server.publicBaseUrl`
`GITTALLY_ARTIFACT_BUILD_RETENTION_PER_BRANCH`	`artifacts.retentionPerBranch` for a count, `artifacts.retentionMaxAge` for a legacy age value (`h`/`d` suffix); unlike legacy, both limits can be combined
`GITTALLY_IMPRESSUM_URL`	`server.impressumUrl`
`GITTALLY_AUTO_BUILD_BRANCHES`	a build definition with `branches: [...]` selecting them
`GITTALLY_AUTO_BUILD_TIMES`	`builds.<name>.atTimes` — YAML list of UTC `HH:MM` slots
`GITTALLY_GITEA_BASE_URL`	`gitea.baseUrl`
`GITTALLY_GITEA_OWNER`	`gitea.owner`
`GITTALLY_GITEA_REPO`	`gitea.repo`
`GITTALLY_GITEA_STATUS_CONTEXT`	`gitea.statusContext`
`GITTALLY_GITEA_GIT_USERNAME`	`git.account` — in `.git/gittally/.gittally.yml`
`GITTALLY_GITEA_TOKEN`	`git.token` — in `.git/gittally/.gittally.yml`, never committed
`GITTALLY_ARTIFACT_NGINX_SERVER_NAME`	`server.nginx.serverName` — also set `server.nginx.enabled: true` (replaces the `--nginx` flag)
`GITTALLY_ARTIFACT_NGINX_HTTP_PORT`	`server.nginx.httpPort`
`GITTALLY_ARTIFACT_NGINX_HTTPS_PORT`	`server.nginx.httpsPort`
`GITTALLY_ARTIFACT_NGINX_UPSTREAM_HOST`	`server.nginx.upstreamHost`
`GITTALLY_ARTIFACT_NGINX_CONTAINER_NAME`	`server.nginx.containerName`
`GITTALLY_ARTIFACT_NGINX_STATE_DIR`	`server.nginx.stateDir`
`GITTALLY_ARTIFACT_LETSENCRYPT_EMAIL`	`server.nginx.letsencryptEmail`

New keys without a legacy counterpart: builds.maxConcurrent, artifacts.rootDir, and watcher.pollInterval.

Intentionally Not Ported

Self-install and self-update (--install, --pull, GITTALLY_INSTALL_DIR) — replaced by jar deployment plus init --systemd.
GITTALLY_BUILD_DOCKER_PREFLIGHT_COMMAND and GITTALLY_BUILD_DOCKER_JAVA_TOOL_OPTIONS — hsadmin-ng-specific; use builds.<name>.docker.env if needed.
HSADMIN_NG_* environment-variable fallbacks.
Env-file configuration itself — the systemd EnvironmentFile now only tunes the JVM (JAVA_OPTS).
GITTALLY_GITEA_DELETED_STATUS_DESCRIPTION, GITTALLY_BIN_FORWARD, GITTALLY_CONFIG_* — internal legacy mechanics without a counterpart.

Build History

Legacy build history (.git/git-watch-origin-and-test/build-results.tsv) is not imported; history starts fresh. The formats differ substantially (TSV vs. JSON with commit metadata and artifact keys), and retention would prune imported rows quickly anyway. Old artifacts under the legacy artifact root remain readable on disk until you delete them.

Manual Migration Steps

When migrating to a different host, the legacy instance can keep running in parallel until the new one is verified — then skip step 1 here and stop the legacy service on the old host last. During parallel operation, give the new instance a distinct gitea.statusContext, so the two instances do not overwrite each other's commit statuses in Gitea.

Rename the context back to the canonical one while no build is running. The Gitea client reads the config per call, so a rename between a build's running and its final status splits that build over two contexts: the old one keeps the pending "build running" entry forever, and Gitea's combined status of that commit stays pending although the build succeeded. Gitea has no API to delete a commit status; the only way out is to post a closing status for the abandoned context by hand:

curl -X POST -H "Authorization: token $TOKEN" -H 'Content-Type: application/json' \
  -d '{"state":"success","context":"<old context>","description":"superseded by <new context>"}' \
  "$GITEA/api/v1/repos/<owner>/<repo>/statuses/<commit-sha>"

Stop and remove the legacy service:

systemctl --user disable --now gitTally.service
rm -f ~/.config/systemd/user/gitTally.service
systemctl --user daemon-reload

Build and place the jar as described in deployment.md.
In the repository, run java -jar ~/bin/gittally.jar init.
Transfer your settings from the legacy env file into .gittally.yml using the table above.
Put git.account and git.token into .git/gittally/.gittally.yml.
Verify the effective configuration: java -jar ~/bin/gittally.jar config:print --full.
Install and start the new service: init --systemd plus the printed commands, see deployment.md.
Optionally clean up legacy state: .git/git-watch-origin-and-test/ and the legacy artifact root.

6.3 KiB Raw Blame History