# wectrl CI Pipeline Templates

Reusable Gitea Actions workflows for all wectrl services. These live in the `wectrl-net/ci-templates` repository and are called from each service repo.

## Setup

### 1. Create the `ci-templates` repo on Gitea

Create a new repo at `git.wectrl.net/wectrl-net/ci-templates` and push the `.gitea/workflows/` directory from this template.

### 2. Required secrets per service repo

Each service repo needs these secrets configured in Gitea (Settings > Actions > Secrets):

| Secret | Description |
|--------|-------------|
| `REGISTRY_USER` | Gitea username for pushing images |
| `REGISTRY_TOKEN` | Gitea token with `packages:write` scope |
| `GIT_USER` | Gitea username for pushing to k8s cluster repo |
| `GIT_TOKEN` | Gitea token with `repo:write` scope on `wectrl-k8s-cluster` |

### 3. Add workflows to your service repo

Copy the appropriate example from `examples/` into your repo's `.gitea/workflows/` directory and customize the parameters.

## Available Templates

### Lint workflows

| Template | Language | Tool |
|----------|----------|------|
| `lint-python.yaml` | Python | Ruff |
| `lint-node.yaml` | Node/TS | ESLint + tsc |
| `lint-rust.yaml` | Rust | Clippy + rustfmt |

### Test workflows

| Template | Language | Tool |
|----------|----------|------|
| `test-python.yaml` | Python | pytest |
| `test-node.yaml` | Node/TS | npm test (Vitest/Jest) |
| `test-rust.yaml` | Rust | cargo test |

### Build & Deploy workflows

| Template | Purpose |
|----------|---------|
| `build-push.yaml` | Build Docker image, push to `git.wectrl.net` registry |
| `deploy-k8s.yaml` | Update image tag in `wectrl-k8s-cluster` repo (ArgoCD GitOps) |

## Examples

### Python + React fullstack (h1per-pms pattern)

```yaml
# .gitea/workflows/ci.yml
name: CI
on:
  pull_request:
    branches: [main, dev]
  push:
    branches: [main, dev]

jobs:
  lint-backend:
    uses: wectrl-net/ci-templates/.gitea/workflows/lint-python.yaml@main
  lint-frontend:
    uses: wectrl-net/ci-templates/.gitea/workflows/lint-node.yaml@main
    with:
      working-directory: web
  test-backend:
    uses: wectrl-net/ci-templates/.gitea/workflows/test-python.yaml@main
  test-frontend:
    uses: wectrl-net/ci-templates/.gitea/workflows/test-node.yaml@main
    with:
      working-directory: web
```

### Rust service (wectrl-telemetry pattern)

```yaml
# .gitea/workflows/ci.yml
name: CI
on:
  pull_request:
    branches: [main, dev]
  push:
    branches: [main, dev]

jobs:
  lint:
    uses: wectrl-net/ci-templates/.gitea/workflows/lint-rust.yaml@main
  test:
    uses: wectrl-net/ci-templates/.gitea/workflows/test-rust.yaml@main
```

## Pipeline flow

```
PR / push to dev     push to main
      │                    │
      ▼                    ▼
  ┌───────┐          ┌───────┐
  │  Lint  │          │  Lint  │
  │  Test  │          │  Test  │
  └───────┘          └───┬───┘
                         │
                         ▼
                   ┌───────────┐
                   │ Build &   │
                   │ Push Image│
                   └─────┬─────┘
                         │
                         ▼
                   ┌───────────┐
                   │ Update    │
                   │ k8s repo  │
                   └─────┬─────┘
                         │
                         ▼
                   ┌───────────┐
                   │ ArgoCD    │
                   │ auto-sync │
                   └───────────┘
```

## Service mapping

| Service | Repo | Stack | Deploy path in k8s-cluster |
|---------|------|-------|---------------------------|
| h1per-pms | `wectrl-net/h1per-pms` | Python + React/TS | `saas/h1per/backend/deployment.yaml` |
| clok1-landing | `wectrl-net/clok1-landing` | Node/TS | `saas/clok1/app/deployment.yaml` |
| solar-platform | `wectrl-net/solar-platform` | TBD | `platform/components/wectrl-solar-platform/api-deployment.yaml` |
| solar-web | `wectrl-net/solar-web` | TBD | `platform/components/wectrl-solar-platform/web-deployment.yaml` |
| client-portal API | `wectrl-net/wectrl-client-portal` | TBD | `platform/components/wectrl-client-portal/api-deployment.yaml` |
| client-portal frontend | `wectrl-net/wectrl-client-portal-frontend` | TBD | `platform/components/wectrl-client-portal/frontend-deployment.yaml` |
| wectrl-telemetry | `wectrl-net/wectrl-telemetry` | Rust | TBD (needs k8s manifests) |

## Customization

All templates accept inputs with sensible defaults. Override only what differs from the standard:

```yaml
jobs:
  lint:
    uses: wectrl-net/ci-templates/.gitea/workflows/lint-python.yaml@main
    with:
      python-version: "3.12"        # override default 3.13
      working-directory: backend     # if Python code is in a subdirectory
```

## Notes

- All workflows trigger on both `main` and `dev` branches (per CON-569 branching strategy)
- Build & deploy only runs on push to `main` (production deploy)
- Dev/staging deploys can be added by extending `deploy-k8s.yaml` with a branch condition
- The runner is ARM64 (`linux/arm64`) matching the Hetzner CAX cluster nodes
- Semantic versioning tags (`v1.2.3`) are supported by `build-push.yaml` via the metadata action