From 677e186286331548b4b20cec30e74878c89a3fd7 Mon Sep 17 00:00:00 2001 From: Aleksei Sviridkin Date: Mon, 13 Apr 2026 02:03:03 +0300 Subject: [PATCH 1/4] [ci] Add Gemini Code Assist configuration Configure the Gemini Code Assist GitHub reviewer with project-specific ignore patterns and a natural-language style guide. The config silences noise from vendored upstream Helm charts, generated Go code, build artifacts, and Grafana dashboard JSONs, while keeping the severity threshold at LOW for strict review of hand-written code. The style guide teaches the reviewer about the vendoring model, commit format requirements, sensitive components like packages/core/platform/, and lists anti-patterns not to flag (patch files, go.sum, upstream forks). Signed-off-by: Aleksei Sviridkin --- .gemini/config.yaml | 23 +++++++++ .gemini/styleguide.md | 107 ++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 130 insertions(+) create mode 100644 .gemini/config.yaml create mode 100644 .gemini/styleguide.md diff --git a/.gemini/config.yaml b/.gemini/config.yaml new file mode 100644 index 00000000..3b5e413e --- /dev/null +++ b/.gemini/config.yaml @@ -0,0 +1,23 @@ +have_fun: false + +ignore_patterns: + - "**/charts/**" + - "**/vendor/**" + - "**/zz_generated.*.go" + - "**/pkg/generated/**" + - "**/_out/**" + - "**/*.tgz" + - "**/dashboards/**/*.json" + - "**/*.patch" + - "**/*.diff" + - "**/images/*.json" + +code_review: + disable: false + comment_severity_threshold: LOW + max_review_comments: 50 + pull_request_opened: + help: false + summary: true + code_review: true + include_drafts: false diff --git a/.gemini/styleguide.md b/.gemini/styleguide.md new file mode 100644 index 00000000..e519f018 --- /dev/null +++ b/.gemini/styleguide.md @@ -0,0 +1,107 @@ +# Cozystack Review Guidelines + +## Project Architecture + +Cozystack is a Kubernetes-based PaaS built on Helm umbrella charts and FluxCD. +Packages live in `packages/{core,system,apps,extra}/`. +Each package wraps one or more upstream Helm charts. +Go code in `cmd/`, `internal/`, `pkg/` implements Kubernetes controllers and API server. +CRDs are in `api/v1alpha1/` and `api/apps/v1alpha1/`. +App Kinds (like `Postgres`, `Kafka`) are registered dynamically at runtime from `ApplicationDefinition` resources — they are not static CRDs. + +## Vendored Code — Critical Rules + +**Never suggest editing files inside any `charts/` directory under `packages/`.** +Those are upstream Helm charts vendored via `make update` (which runs `helm pull`). +Any direct edit is overwritten on the next update and provides zero value. + +If you find an issue that appears to live in vendored chart code: + +- For configuration-level changes: suggest overrides in the package root `values.yaml`. +- For structural changes: suggest a patch file in `packages//patches/` applied by the Makefile. +- For source-code changes in images: suggest a patch in `packages//images//patches/`. +- For true upstream bugs: point to the upstream repository and suggest an upstream issue/PR. +- Do NOT suggest creating `charts/patches/` — patches never live inside `charts/`. + +Similarly, never propose edits to: + +- `vendor/` — Go dependencies. Changes go through `go get` and `go mod tidy`. +- `zz_generated.*.go` — regenerated by `make generate`. +- `pkg/generated/` — auto-generated Kubernetes client code. +- Image digest values in `values.yaml` — set by CI via `make image`, not by humans. +- `go.mod` / `go.sum` by hand — use `go get` and `go mod tidy`. + +## Commit and PR Requirements + +Each commit must start with a component prefix: `[component] Brief description`. + +Valid prefixes: + +- System: `[dashboard]`, `[platform]`, `[cilium]`, `[kube-ovn]`, `[linstor]`, `[fluxcd]`, `[cluster-api]` +- Apps: `[postgres]`, `[mariadb]`, `[redis]`, `[kafka]`, `[clickhouse]`, `[kubernetes]`, `[virtual-machine]` +- Meta: `[tests]`, `[ci]`, `[docs]`, `[maintenance]` +- Package-specific: any `[]` matching a directory under `packages/` + +Each commit must have a `Signed-off-by:` trailer (produced by `git commit --signoff`). + +PR body must contain a release note block: + +```text + ```release-note + [component] Human-readable changelog entry + ``` +``` + +Flag any PR whose commits lack the prefix or signoff, or whose body has no release-note block. + +## Helm Chart Conventions + +Packages follow an umbrella chart pattern: + +- `charts/` — vendored upstream, read-only +- `templates/` — Cozystack-specific extra manifests +- `values.yaml` — override values for the upstream chart +- `values.schema.json` — JSON Schema for dashboard UI and input validation + +When reviewing `values.schema.json`: + +- `make generate` regenerates this file and strips `title`, `description`, and `x-*` custom annotations. Do not suggest adding fields that will be stripped on the next regeneration. +- Focus on type correctness, `required` fields, `enum` values, and default values. +- Flag breaking changes: removing a field, changing its type, or narrowing its enum. + +## Sensitive Components + +**`packages/core/platform/`**: the platform chart that deploys everything. Changes here can require migration scripts in `scripts/migrations/`. Flag any change to this package that lacks a corresponding migration script or an explicit note that backward compatibility is preserved. + +**`api/apps/v1alpha1/`**: app CRD Kinds are registered at runtime from `ApplicationDefinition` resources and the matching `values.schema.json`. Suggest changes to the relevant package schema rather than hand-editing generated types. + +**RBAC, ServiceAccounts, and SecurityContext**: flag overly broad RBAC (`*` on resources or verbs without justification), missing `securityContext`, containers running as root without an explicit reason, and `hostPath`/`hostNetwork` usage without clear rationale. + +## Go Code Standards + +- Use controller-runtime patterns for reconcilers. +- Use structured logging via `logr` — flag `fmt.Print*` and `log.Print*` in controller code. +- Handle errors explicitly. Discarding meaningful errors with `_` is a bug. +- Propagate `context.Context` through call chains. Flag `context.Background()` created inside a reconciler or request handler. +- Prefer `ctrl.Result{RequeueAfter: ...}` over empty requeue for predictable reconciliation loops. +- Tests live beside the code (`*_test.go`). New behavior without tests is worth flagging. + +## What to Review Carefully + +- Logic errors, off-by-one bugs, nil dereferences. +- Missing error handling, especially in reconcilers and API handlers. +- Helm template correctness: missing `quote`, incorrect indentation, wrong scope in `with`/`range`. +- Security: permissive RBAC, privileged containers, secrets in environment variables, hardcoded credentials. +- Missing resource requests/limits on new workloads. +- Breaking changes in `values.schema.json`: removed fields, tightened types, narrower enums. + +## Anti-patterns — Do Not Flag These + +- Large JSON files in `dashboards/` — imported from upstream Grafana sources, not hand-written. +- `*.tgz` files — Helm chart archives, expected in the repo. +- Files under any `charts/` directory — vendored upstream, left as-is intentionally. +- Whitespace or formatting in `*.patch` / `*.diff` files — machine-applied, not authored. +- Missing comments on generated code. +- `go.sum` changes accompanying `go.mod` changes — expected and correct. +- Fork relationships for vendored tooling images — intentional (e.g., `cozystack/kilo` fork is expected). +- Absence of unit tests for vendored chart overrides — covered by E2E tests in `hack/e2e-apps/`. From b74a9610d4da03f32faab50ce73b333b421deb68 Mon Sep 17 00:00:00 2001 From: Aleksei Sviridkin Date: Mon, 13 Apr 2026 13:27:35 +0300 Subject: [PATCH 2/4] [ci] Address CodeRabbit feedback on Gemini style guide Fix two issues caught in PR review: - Use quadruple-backtick fence around the release-note example so the inner triple-backtick block renders correctly and satisfies markdownlint. - Correct the platform migration path. The previous text pointed at scripts/migrations/, which does not exist. The actual migration flow lives in packages/core/platform/templates/migration-hook.yaml and packages/core/platform/images/migrations/. Signed-off-by: Aleksei Sviridkin --- .gemini/styleguide.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/.gemini/styleguide.md b/.gemini/styleguide.md index e519f018..64f9adb3 100644 --- a/.gemini/styleguide.md +++ b/.gemini/styleguide.md @@ -46,11 +46,11 @@ Each commit must have a `Signed-off-by:` trailer (produced by `git commit --sign PR body must contain a release note block: -```text - ```release-note - [component] Human-readable changelog entry - ``` +````text +```release-note +[component] Human-readable changelog entry ``` +```` Flag any PR whose commits lack the prefix or signoff, or whose body has no release-note block. @@ -71,7 +71,7 @@ When reviewing `values.schema.json`: ## Sensitive Components -**`packages/core/platform/`**: the platform chart that deploys everything. Changes here can require migration scripts in `scripts/migrations/`. Flag any change to this package that lacks a corresponding migration script or an explicit note that backward compatibility is preserved. +**`packages/core/platform/`**: the platform chart that deploys everything. Changes here can require updates to the migration flow — the Helm hook in `packages/core/platform/templates/migration-hook.yaml` and the runner image with scripts in `packages/core/platform/images/migrations/`. Flag any change to this package that lacks a corresponding migration update or an explicit note that backward compatibility is preserved. **`api/apps/v1alpha1/`**: app CRD Kinds are registered at runtime from `ApplicationDefinition` resources and the matching `values.schema.json`. Suggest changes to the relevant package schema rather than hand-editing generated types. From c8488815e0c59b26093c459d1da98db627470410 Mon Sep 17 00:00:00 2001 From: Aleksei Sviridkin Date: Mon, 13 Apr 2026 13:32:15 +0300 Subject: [PATCH 3/4] [ci] Enable CodeRabbit incremental reviews Add a minimal .coderabbit.yaml that ensures CodeRabbit re-reviews each push to a PR (incremental review on new commits) and skips drafts. Without this file, the org-level configuration left incremental reviews disabled, so only the initial PR open triggered a review. Signed-off-by: Aleksei Sviridkin --- .coderabbit.yaml | 5 +++++ 1 file changed, 5 insertions(+) create mode 100644 .coderabbit.yaml diff --git a/.coderabbit.yaml b/.coderabbit.yaml new file mode 100644 index 00000000..46a4f0b9 --- /dev/null +++ b/.coderabbit.yaml @@ -0,0 +1,5 @@ +reviews: + auto_review: + enabled: true + auto_incremental_review: true + drafts: false From 81a0d523d6f85a952f9e53c6a7de88039dc6863c Mon Sep 17 00:00:00 2001 From: Aleksei Sviridkin Date: Mon, 13 Apr 2026 17:18:34 +0300 Subject: [PATCH 4/4] [ci] Fix factual errors in Gemini style guide MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Three corrections from PR review: - Package group list was incomplete. Added library/ (reusable helper charts) and tests/ (tests for library charts, which are not directly testable otherwise). - CRD generation was described incorrectly. Static CRDs are generated by hack/update-codegen.sh from types under api/v1alpha1/, api/backups/, and api/dashboard/. Types under api/apps/v1alpha1/ are not static CRDs — they are registered at runtime from ApplicationDefinition. - Removed the tgz anti-pattern. No *.tgz files exist outside _out/, which is gitignored. The guidance was fabricated. Signed-off-by: Aleksei Sviridkin --- .gemini/styleguide.md | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/.gemini/styleguide.md b/.gemini/styleguide.md index 64f9adb3..00201bfb 100644 --- a/.gemini/styleguide.md +++ b/.gemini/styleguide.md @@ -3,11 +3,11 @@ ## Project Architecture Cozystack is a Kubernetes-based PaaS built on Helm umbrella charts and FluxCD. -Packages live in `packages/{core,system,apps,extra}/`. +Packages live in `packages/{core,system,apps,extra,library,tests}/`. The `library/` group holds reusable helper charts; the `tests/` group exists because library charts are not directly testable. Each package wraps one or more upstream Helm charts. Go code in `cmd/`, `internal/`, `pkg/` implements Kubernetes controllers and API server. -CRDs are in `api/v1alpha1/` and `api/apps/v1alpha1/`. -App Kinds (like `Postgres`, `Kafka`) are registered dynamically at runtime from `ApplicationDefinition` resources — they are not static CRDs. +Static CRDs are generated by `hack/update-codegen.sh` from types under `api/v1alpha1/`, `api/backups/`, and `api/dashboard/`. +App Kinds (like `Postgres`, `Kafka`) live in `api/apps/v1alpha1/` but are registered dynamically at runtime from `ApplicationDefinition` resources — they are not static CRDs. ## Vendored Code — Critical Rules @@ -98,7 +98,6 @@ When reviewing `values.schema.json`: ## Anti-patterns — Do Not Flag These - Large JSON files in `dashboards/` — imported from upstream Grafana sources, not hand-written. -- `*.tgz` files — Helm chart archives, expected in the repo. - Files under any `charts/` directory — vendored upstream, left as-is intentionally. - Whitespace or formatting in `*.patch` / `*.diff` files — machine-applied, not authored. - Missing comments on generated code.