Sanitized mirror from private repository - 2026-03-24 12:45:58 UTC

docs/guides/renovate-bot.md

@@ -0,0 +1,83 @@
+# Renovate Bot
+
+Renovate automatically opens PRs in the `Vish/homelab` Gitea repo when Docker image tags in compose files are outdated. This keeps images from drifting too far behind upstream.
+
+## How It Works
+
+1. Gitea Actions runs `renovate/renovate` on a weekly schedule (Mondays 06:00 UTC)
+2. Renovate scans all `docker-compose*.yaml` / `.yml` files in the repo
+3. For each pinned image tag (e.g. `influxdb:2.2`), it checks Docker Hub for newer versions
+4. Opens a PR with the updated tag and changelog link
+5. PRs are **not auto-merged** — requires manual review
+
+## Files
+
+| File | Purpose |
+|------|---------|
+| `renovate.json` | Renovate configuration |
+| `.gitea/workflows/renovate.yml` | Gitea Actions workflow |
+
+## Configuration (`renovate.json`)
+
+```json
+{
+  "extends": ["config:base"],
+  "ignorePaths": ["archive/**"],
+  "packageRules": [
+    {
+      "matchManagers": ["docker-compose"],
+      "automerge": false,
+      "labels": ["renovate", "dependencies"]
+    }
+  ]
+}
+```
+
+- `archive/**` is excluded — archived stacks shouldn't generate noise
+- All PRs get `renovate` and `dependencies` labels
+- `automerge: false` — always review before applying
+
+## Gitea Secret
+
+`RENOVATE_TOKEN` is set in `Vish/homelab → Settings → Actions → Secrets`.
+The PAT must have at minimum: **repo read/write** and **issues write** permissions (to open PRs).
+
+## Triggering Manually
+
+From Gitea: **Actions → Renovate → Run workflow**
+
+Or via API:
+```bash
+curl -X POST "https://git.vish.gg/api/v1/repos/Vish/homelab/actions/workflows/renovate.yml/dispatches" \
+  -H "Authorization: token <your-pat>" \
+  -H "Content-Type: application/json" \
+  -d '{"ref":"main"}'
+```
+
+## What Renovate Updates
+
+Renovate's `docker-compose` manager detects image tags in:
+- `image: nginx:1.25` → tracks nginx versions
+- `image: influxdb:2.2` → tracks influxdb 2.x
+- `image: ghcr.io/analogj/scrutiny:master-web` → tracks by SHA digest (floating tags)
+
+Floating tags like `latest` or `master-*` are tracked by digest — Renovate opens a PR when the digest changes, even if the tag doesn't change.
+
+## Troubleshooting
+
+**Workflow fails: "docker: not found"**
+→ The `python` runner must have Docker available. Check the runner's environment.
+
+**No PRs opened despite outdated images**
+→ Check `LOG_LEVEL=debug` output in the Actions run. Common causes:
+  - Image uses a floating tag with no semver (Renovate may skip it)
+  - `ignorePaths` too broad
+  - Gitea API permissions insufficient for the PAT
+
+**PRs pile up**
+→ Merge or close stale ones. Add `ignoreDeps` entries to `renovate.json` for images you intentionally pin:
+```json
+{
+  "ignoreDeps": ["favonia/cloudflare-ddns"]
+}
+```