docs: add Forgejo runner deployment guide

2026-09-06 06:40:00 -07:00
parent 1630766a47
commit 862d420295
1 changed files with 116 additions and 0 deletions
@@ -0,0 +1,116 @@
+# Forgejo Runner Deployment Guide
+
+## Status
+❌ **No runners currently deployed** — Workflow will not trigger without them.
+
+## Issue
+The CI/CD workflow is ready in `.gitea/workflows/build.yaml`, but **requires Forgejo runners** to execute.
+
+## Solution: Deploy Runners via Helm
+
+### 1. Check if Helm chart is available
+
+```bash
+helm repo add code.forgejo.org https://forgejo.io/helm-charts
+helm repo update
+helm search repo forgejo-runner
+```
+
+### 2. Deploy Rust Runner (for memory service)
+
+```bash
+cd /Users/rockliang/workplace/homelab/k8s/infra/forgejo-runner
+
+# Deploy golang runner (base)
+helm install forgejo-runner code.forgejo.org/forgejo-runner \
+  --namespace cicd \
+  --create-namespace \
+  -f values.yaml
+
+# Deploy rust runner (overlay)
+helm install forgejo-runner-rust code.forgejo.org/forgejo-runner \
+  --namespace cicd \
+  -f values.yaml \
+  -f values-rust.yaml
+```
+
+### 3. Verify Runners are Running
+
+```bash
+kubectl get pod -n cicd -l app.kubernetes.io/name=runner
+# Should show:
+# NAME                          READY   STATUS    RESTARTS
+# forgejo-runner-golang-xyz     1/1     Running   0
+# forgejo-runner-rust-abc       1/1     Running   0
+```
+
+### 4. Check Runner Registration in Forgejo
+
+```bash
+# Visit Forgejo web UI: https://forgejo.riotpiao.com
+# Admin → Runners → Should show "rust" and "golang" runners
+```
+
+### 5. Trigger CI/CD
+
+Once runners are ready:
+1. **Create PR**: Push to feature branch → CI job runs (test only)
+2. **Merge to main**: Merge PR → Both test and build jobs run
+3. **Check image**: Docker image pushed to `forgejo.riotpiao.com/rock/poimen-memory:latest`
+
+## Workflow Execution Timeline
+
+```
+Push to feature branch
+  ↓
+CI job runs (test + check)
+  ├─ cargo test -p mem-ingest --lib
+  ├─ cargo check -p mem-ingest
+  └─ ✅ or ❌ Pass/Fail (no build)
+
+Merge to main
+  ↓
+Test job runs again
+  ├─ cargo test -p mem-ingest --lib
+  ├─ cargo check -p mem-ingest
+  ↓ (if pass)
+Build job runs (ONLY on main)
+  ├─ docker build
+  ├─ docker login
+  ├─ docker push
+  └─ image: forgejo.riotpiao.com/rock/poimen-memory:latest ✅
+```
+
+## Troubleshooting
+
+### Workflow doesn't start
+- Check runners are running: `kubectl get pod -n cicd`
+- Check runner registration in Forgejo UI
+- Check runner labels match workflow `runs-on: rust`
+
+### Test fails but build still runs
+- Check workflow condition: `if: github.event_name == 'push' && github.ref == 'refs/heads/main'`
+- Build requires `needs: test` — should wait for test job
+
+### Docker push fails
+- Verify `REGISTRY_PAT` secret exists in Forgejo
+- Check credentials: `echo ${{ secrets.REGISTRY_PAT }} | docker login -u rock --password-stdin forgejo.riotpiao.com`
+
+### Image not in registry
+- Check build logs: Forgejo UI → Repo → Actions
+- Verify registry URL in workflow: `forgejo.riotpiao.com`
+- Check docker is available on runner: `docker --version`
+
+## Files
+
+- `.gitea/workflows/build.yaml` — CI/CD workflow (test on PR, build on main)
+- `homelab/k8s/infra/forgejo-runner/values.yaml` — Base runner config
+- `homelab/k8s/infra/forgejo-runner/values-rust.yaml` — Rust runner overlay
+- `Dockerfile` — Multi-stage Rust build
+
+## Next Steps
+
+1. **Deploy runners** (follow section 2 above)
+2. **Create a test PR** to verify CI triggers
+3. **Merge to main** to verify build + push works
+4. **Check registry** for new image tags