feat: add reusable CI/CD pipeline templates

Reusable Gitea Actions workflows for lint, test, build, and deploy: - lint-python, lint-node, lint-rust - test-python, test-node, test-rust - build-push (Docker build + push to Gitea registry) - deploy-k8s (GitOps image tag update in cluster repo) Plus example caller workflows for python-fullstack, rust-service, and node-frontend stacks. Branch refs aligned to staging per CON-570 standards.
2026-03-31 19:55:17 +03:00
parent 491bb8dbfd
commit a620868998
15 changed files with 783 additions and 2 deletions
--- a/README.md
+++ b/README.md
@@ -1,3 +1,158 @@
-# ci-templates
+# wectrl CI Pipeline Templates

-Reusable CI/CD pipeline templates for Gitea Actions
+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