From 3e7c0e52a7474a749c04a27d5659522595ff6da8 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Mattias=20=C3=85sell?= Date: Mon, 5 Oct 2026 20:52:49 +0200 Subject: [PATCH] skills(ankra-applications): document .ankra/ankra.yaml and its components block The setup PR carries the application descriptor; say what it holds (metadata, the deploy options contract) and that a components: block declares a monorepo's components, outranks every inferred signal, is the only way to remove a component, and is refused whole as the read_declared_components task. reference.md gets the Cadence-shaped declaration example. Both link the new docs reference page. Co-Authored-By: Claude Opus 5.5 --- .../skills/ankra-applications/SKILL.md | 9 +++++++++ .../skills/ankra-applications/reference.md | 19 +++++++++++++++++++ 2 files changed, 28 insertions(+) diff --git a/internal/skills/embedded/skills/ankra-applications/SKILL.md b/internal/skills/embedded/skills/ankra-applications/SKILL.md index 7e090a79..dd8ca1c4 100644 --- a/internal/skills/embedded/skills/ankra-applications/SKILL.md +++ b/internal/skills/embedded/skills/ankra-applications/SKILL.md @@ -103,6 +103,15 @@ ankra application retry # re-run a failed setup Things worth checking before merging: the base image and its tag, the exposed port, the health probe paths, resource requests, and that nothing secret was baked into the image. +The PR also carries `.ankra/ankra.yaml`, the application descriptor: `metadata`, the `options` that +are the deploy form's contract (edit them in Git and re-run setup to change the form), and an +optional `components:` block. When analysis reads a monorepo wrong (an API at the root built from +`deploy/docker/Dockerfile` beside a `web/` app reads as one app), declare the components there +(`name`, `subdir`, `dockerfile`, `container_port`) and reconcile: a declaration outranks the existing +workflows, the AI proposal and structural detection, and is the only way to remove a component. A +block Ankra cannot honour is refused whole, reported as the `read_declared_components` setup task, +and the recorded components are kept. Schema: https://docs.ankra.ai/reference/application-descriptor + ## 3. Supply configuration and secrets The generated manifests declare which environment values they need. Fill them in — a missing one diff --git a/internal/skills/embedded/skills/ankra-applications/reference.md b/internal/skills/embedded/skills/ankra-applications/reference.md index d4b00c34..99b90e3e 100644 --- a/internal/skills/embedded/skills/ankra-applications/reference.md +++ b/internal/skills/embedded/skills/ankra-applications/reference.md @@ -45,6 +45,25 @@ ankra application registry set \ ### Monorepo components +Ankra infers the components, but a repository can declare them in `.ankra/ankra.yaml`, and the +declaration wins over every inferred signal: + +```yaml +components: + - name: api + subdir: "" + dockerfile: deploy/docker/Dockerfile + container_port: 8080 + - name: web + subdir: web + container_port: 3000 +``` + +Names are lower-case letters and digits joined by hyphens or periods (they name the image repository +and the `build-` stage). Paths are relative to the repository root. Inference never shrinks a +recorded monorepo; only a declaration removes a component. Full schema: +https://docs.ankra.ai/reference/application-descriptor + ```bash ankra application registry set \ --url oci://artifact.example.com/commerce \