# Werkator

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

## Documentation

- [docs/configuration.md](docs/configuration.md) — configuration reference
- [docs/bootstrapping.md](docs/bootstrapping.md) — initializing a repository with `init`
- [docs/deployment.md](docs/deployment.md) — running 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:

```bash
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:

```yaml
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](#direnv) to have this done automatically on `cd`:

```bash
source .envrc
```

Common tasks:

```bash
./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](https://direnv.net/) sources `.envrc` automatically whenever you enter the repository and unloads it when you leave.

```bash
# 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:

```bash
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/`](docs/adrs/).

```bash
adr-status   # show all decisions at a glance
```

New ADRs follow the template at [`docs/adrs/0000-00-00.adr-template.md`](docs/adrs/0000-00-00.adr-template.md).