From 6888b6c925f2cc8caeb6bb5de3ef80fd41bcf06b Mon Sep 17 00:00:00 2001 From: Jarvis Date: Mon, 17 Aug 2026 09:55:23 +0800 Subject: [PATCH 1/2] docs(agents): clarify that the portal chart still ships releases for new config MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit "Do not add per-field values keys" read as "the chart never changes when the application adds config", which would leave users with no way to discover a new option — values.yaml is where they look. The rule is about not hoisting schema fields into dedicated keys with their own template plumbing; new config still gets a commented example under developerPortal.config and a chart release. --- AGENTS.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/AGENTS.md b/AGENTS.md index 7fe9763..84f85c5 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -75,7 +75,9 @@ When adding values, keep defaults identical to `config-default.yaml` so a defaul ## developer-portal-fe chart: config is a pass-through -`config.yaml` is rendered from `developerPortal.config`, which carries the application's whole config schema. **Do not add per-field `.Values` keys for it** — the schema lives in `api7/api7ee-developer-portal` (`apps/site/src/lib/config/schema.ts`) and mirroring it drifts on every application release. Only the connection settings the chart itself owns are templated, and they are merged over the block so a user cannot move the Secret-backed `${PORTAL_TOKEN}` / `${DB_URL}` / `${AUTH_SECRET}` placeholders into the ConfigMap. +`config.yaml` is rendered from `developerPortal.config`, which carries the application's whole config schema (owned by `api7/api7ee-developer-portal`, `apps/site/src/lib/config/schema.ts`). **Do not hoist schema fields into their own `.Values` keys** — a dedicated key plus template plumbing per field mirrors that schema, drifts on every application release, and leaves two ways to set one field. Only the connection settings the chart itself owns are templated, and they are merged over the block so a user cannot move the Secret-backed `${PORTAL_TOKEN}` / `${DB_URL}` / `${AUTH_SECRET}` placeholders into the ConfigMap. + +That is not a licence to skip chart releases: pass-through only means a user is never *blocked* on one, while `values.yaml` is still how they find out an option exists. When the application adds config worth surfacing, add it under `developerPortal.config` and cut a chart release. Write it as a commented example rather than a live default — a live default pins the application's default of that day into the chart and keeps overriding it after the application moves on. To verify a rendered config, run it through the image's own loader: `docker run --rm -v $PWD/config.yaml:/app/apps/site/config.yaml -e PORTAL_TOKEN=x -e DB_URL=x -e AUTH_SECRET=$(head -c 32 /dev/zero | tr '\0' a) --entrypoint sh api7/api7-ee-developer-portal-fe: -c 'node preflight.js'` — reaching the `Portal URL:` line means the config validated (the portal/database checks after it need a live backend). That mount path is fixed: the standalone server chdirs into `apps/site`, and preflight looks there. From d4d65a6ee1d22080c7c05c40b11160cb67d51bad Mon Sep 17 00:00:00 2001 From: Jarvis Date: Mon, 17 Aug 2026 09:58:23 +0800 Subject: [PATCH 2/2] docs(agents): say what the merge actually prevents The placeholders live in the ConfigMap by design; what a user cannot do is replace them with literal credentials. --- AGENTS.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/AGENTS.md b/AGENTS.md index 84f85c5..0475538 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -75,7 +75,7 @@ When adding values, keep defaults identical to `config-default.yaml` so a defaul ## developer-portal-fe chart: config is a pass-through -`config.yaml` is rendered from `developerPortal.config`, which carries the application's whole config schema (owned by `api7/api7ee-developer-portal`, `apps/site/src/lib/config/schema.ts`). **Do not hoist schema fields into their own `.Values` keys** — a dedicated key plus template plumbing per field mirrors that schema, drifts on every application release, and leaves two ways to set one field. Only the connection settings the chart itself owns are templated, and they are merged over the block so a user cannot move the Secret-backed `${PORTAL_TOKEN}` / `${DB_URL}` / `${AUTH_SECRET}` placeholders into the ConfigMap. +`config.yaml` is rendered from `developerPortal.config`, which carries the application's whole config schema (owned by `api7/api7ee-developer-portal`, `apps/site/src/lib/config/schema.ts`). **Do not hoist schema fields into their own `.Values` keys** — a dedicated key plus template plumbing per field mirrors that schema, drifts on every application release, and leaves two ways to set one field. Only the connection settings the chart itself owns are templated, and they are merged over the block, so a user cannot replace the `${PORTAL_TOKEN}` / `${DB_URL}` / `${AUTH_SECRET}` placeholders with literal credentials — those placeholders stay in the ConfigMap and resolve from Secret-backed env vars at startup. That is not a licence to skip chart releases: pass-through only means a user is never *blocked* on one, while `values.yaml` is still how they find out an option exists. When the application adds config worth surfacing, add it under `developerPortal.config` and cut a chart release. Write it as a commented example rather than a live default — a live default pins the application's default of that day into the chart and keeps overriding it after the application moves on.