# 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