werkator/README.md

Werkator

Lightweight, declarative and highly opinionated software build system (CI/CD).

Documentation

• docs/configuration.md — configuration reference
• docs/bootstrapping.md — initializing a repository with init
• docs/deployment.md — running Werkator as a systemd service behind a reverse proxy

Adding a Gitea Repository

One instance serves several repositories (docs/deployment.md, ADR 0009). From the workstation, clone and initialise, then register:

tools/remote --env-file .env.<instance> werkator repo-add https://gitea.example.org/<owner>/<repo>.git [<name>]

It prints the registry entry: add it to ~/.werkator.yml under repositories:, then restart the service. The optional [<name>] overrides the directory basename: it becomes the route segment (/repos/<name>/…) and the UI switcher entry, so it must be unique. Needed only when the clone directory name is wrong or collides — e.g. michael.hoennig.de.git checked out as michael.hoennig.de, or two forges serving a repo of the same name. A public repository needs nothing else: the clone runs anonymously. A private repository needs shared credentials once on the host, in ~/.werkator.yml of the service user, before cloning:

defaults:
  git:
    account: <gitea-user>
    token: <token>   # Gitea → Settings → Applications → Generate Token, scope read:repository

Developer Setup

Source .envrc to add tools/ to your PATH, or install direnv to have this done automatically on cd:

source .envrc

Common tasks:

./gradlew build          # compile and run all checks
./gradlew test           # run tests
./gradlew ktlintFormat   # auto-format Kotlin sources
./gradlew ktlintCheck    # check formatting (also runs as part of build)

adr-status               # show all architecture decisions at a glance

direnv

direnv sources .envrc automatically whenever you enter the repository and unloads it when you leave.

# Ubuntu
sudo apt install direnv

# add to ~/.bashrc or ~/.zshrc
eval "$(direnv hook bash)"   # or: eval "$(direnv hook zsh)"

Trust the project's .envrc once per clone:

direnv allow

Tools (tools/)

Command	Description
adr-status	List all Architecture Decision Records with their status and decision summary

Architecture Decision Records

Major technical decisions are documented as ADRs in docs/adrs/.

adr-status   # show all decisions at a glance

New ADRs follow the template at docs/adrs/0000-00-00.adr-template.md.