Feature/remote authenticated clone (#24)

Co-authored-by: mhoennig <michael@hoennig.de> Reviewed-on: #24
2026-09-05 14:06:58 +02:00
parent cd6f915231
commit 5c64391f5f
4 changed files with 179 additions and 16 deletions
@@ -8,6 +8,28 @@ Lightweight, declarative and highly opinionated software build system (CI/CD).
 - [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`: