Add Gitea Actions workflows, CI config, and docs

docs/DOCKER.md

@@ -0,0 +1,104 @@
+# Docker Build & Registry — ${REPO_NAME}
+
+## Overview
+
+The Docker workflow (`.gitea/workflows/docker.yml`) builds Docker images and
+optionally pushes them to the Gitea Container Registry.
+
+## Gitea Container Registry Naming Convention
+
+Gitea's registry follows this pattern:
+
+```
+{REGISTRY_HOST}/{OWNER}/{IMAGE}:{TAG}
+```
+
+Example:
+```
+git.hiddenden.cafe/myorg/myapp:1.2.3
+```
+
+This is different from Docker Hub (`docker.io/library/myapp:latest`).
+The workflow enforces this format automatically.
+
+## Dynamic Owner/Repo Derivation
+
+The workflow dynamically determines the image owner and name so it works
+for both user repos and organization repos without hardcoding.
+
+**Logic:**
+1. Determine `FULL_REPO` from (in priority order):
+   - `$GITEA_REPOSITORY` (Gitea native environment variable)
+   - `${{ github.repository }}` (Gitea Actions compatibility layer)
+2. Split into `OWNER` (before `/`) and `REPO` (after `/`).
+3. If `IMAGE_OWNER=auto` in config → use `OWNER`; else use the config value.
+4. If `IMAGE_NAME=auto` in config → use `REPO`; else use the config value.
+
+This means you rarely need to change `IMAGE_OWNER` or `IMAGE_NAME`.
+
+## Triggers & Push Behavior
+
+| Event | Build? | Push? | Condition |
+|-------|--------|-------|-----------|
+| Pull Request | Yes | **No** | Never pushes on PRs |
+| Push to `main` | Yes | Conditional | `DOCKER_PUSH=true` AND `DOCKER_PUSH_ON_BRANCH=true` |
+| Tag `v1.2.3` | Yes | Conditional | `DOCKER_PUSH=true` AND `DOCKER_PUSH_ON_TAG=true` |
+
+**Safe default**: `DOCKER_PUSH=false` — images are built but never pushed.
+
+## Tag Strategy
+
+Controlled by `DOCKER_TAG_STRATEGY` in `.ci/config.env`:
+
+### `semver+latest` (default)
+- Tag `v1.2.3` → pushes `:1.2.3` and `:latest`
+- Push to `main` → pushes `:main`
+
+### `semver`
+- Tag `v1.2.3` → pushes `:1.2.3` only
+- Push to `main` → pushes `:main`
+
+### `branch`
+- Branch pushes only, tagged as `:branchname`
+
+## Required Secrets
+
+To push images, set these secrets in your Gitea repository
+(Settings → Actions → Secrets):
+
+| Secret | Description |
+|--------|-------------|
+| `REGISTRY_USERNAME` | Gitea username or bot account name |
+| `REGISTRY_TOKEN` | Personal Access Token with `package:write` scope |
+
+### Creating a PAT
+
+1. Go to **Settings → Applications → Generate New Token**
+2. Name: e.g., `ci-docker-push`
+3. Scopes: select **`package`** (read + write)
+4. Copy the token and add it as `REGISTRY_TOKEN` in repo secrets
+
+**Why PAT instead of job token?**
+Gitea Actions job tokens may not have sufficient permissions for the
+container registry in all configurations. PATs are the recommended approach.
+
+## Detection
+
+The workflow auto-detects how to build:
+
+1. **Dockerfile** → `docker build -t <image>:<tag> .`
+2. **docker-compose.yml** → `docker compose build`
+3. **Neither** → exits 0 with a message (graceful skip)
+
+## Enabling Docker Push
+
+1. Set `DOCKER_PUSH=true` in `.ci/config.env`
+2. Add `REGISTRY_USERNAME` and `REGISTRY_TOKEN` secrets
+3. Push a commit or tag — the workflow will build and push
+
+## Pulling Images
+
+After pushing, pull images with:
+```bash
+docker pull git.hiddenden.cafe/<owner>/<repo>:latest
+```