poimen-memory/docs/operations/RUNNER_DEPLOYMENT.md

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

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)

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

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

# 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