Skip to main content
.ankra/ankra.yaml is an application’s descriptor. Ankra writes it into the setup pull request beside .ankra/manifests/ and .ankra/pipeline.yaml, and reads it back from the tracked branch on every analysis run, so what the file says in Git is what the application is:
  • metadata describes the application, in the shape of a Helm Chart.yaml.
  • options is the application’s deploy-time contract: the inputs the deploy form asks for and the deploy endpoint validates.
  • components (optional) declares the application’s deployable components, for a repository whose layout Ankra cannot infer correctly on its own.
  • health (optional) declares the application’s liveness and readiness routes and a latency budget. The readiness gate, a platform setting, reads the readiness routes and the budget.

Full example

The descriptor of a repository with a Go API at the root, built from deploy/docker/Dockerfile, and a web app in web/:
A generated descriptor lists all fifteen default options (below); the example shows two to stay short.

Top-level keys

Any other top-level key is ignored. Keep the file at .ankra/ankra.yaml, outside .ankra/manifests/: the files in that directory are the manifests a deploy applies to the cluster.

A file Ankra cannot read

A descriptor does not parse when it is empty or not valid YAML, has the wrong apiVersion or kind, has an options value that is not a list, has an option without a name or whose name uses anything but letters, digits and underscores, has an option whose default or description is not a single value, or has a value of the wrong type, such as a list where a string belongs. A refused components or health block does not stop the rest of the file parsing (see A declaration Ankra cannot honour and Health). Every analysis run reads the file from the tracked branch, and what the run could read decides the deploy options and the components:

Metadata

Every field except name is optional. Ankra fills them from the repository’s GitHub metadata when it generates the file and leaves out the ones it could not read. When you publish the application as an add-on, the descriptor travels with the manifests into the add-on version.

Options

options is the application’s deploy contract. The deploy form renders one input per option, the deploy endpoint validates the values against it, and a manifest under .ankra/manifests/ reads a value as ${{ ankra.<name> }}. A non-empty options list replaces the application’s stored contract on the next analysis run, so editing the list in Git and running setup again changes the deploy form. An empty or absent list keeps the contract Ankra generated: there is no way to declare a deliberately empty contract.

Default options

A generated descriptor declares these fifteen options. target_port defaults to the port the analysis detected. An application with a detected database carries that database’s sizing options as well. A deploy checks CPU and memory before it starts, over the deploy API, ankra application deploy --set and ankra application ship --set, and in chat and MCP. Each of cpu_request, cpu_limit, memory_request and memory_limit must be a Kubernetes quantity such as 250m or 512Mi, or empty to clear it. A request cannot be above its limit. The limit it is compared with is the one sent, else the one the environment already has, else the default. A deploy that fails the check changes nothing and answers 422 with: “CPU and memory must be quantities such as 250m or 512Mi, and a request cannot be above its limit.”

Components

components declares the application’s deployable components. Without it, Ankra infers them from the repository (see Monorepos). Inference cannot see every layout: a repository whose API builds from deploy/docker/Dockerfile at the root and whose web app sits in web/ reads as one app, because detection needs two subdirectory Dockerfiles and ignores deploy/. The declaration is how such a repository states its components. subdir and dockerfile are both paths from the repository root, like context and dockerfile in a pipeline build stage. Neither may be absolute or contain ...

The declaration outranks inference

Ankra decides an application’s components in this order, and the first signal that holds wins:
  1. The components block of .ankra/ankra.yaml.
  2. The per-component build workflows the repository already carries.
  3. The apps the analysis proposed on this run.
  4. The repository’s structure.
So a declaration outranks the existing workflows, the AI proposal and structural detection. Two signals can leave a monorepo with fewer components than it records: a declaration, and two or more of Ankra’s per-component build workflows for fewer components than the record (an application built by Ankra Pipelines has no per-component workflows). The AI proposal and structural detection cannot: when they find fewer components than a monorepo already records, Ankra keeps the recorded ones, because finding less is not evidence that a component is gone. To drop a component, declare the ones you keep. When a run’s components no longer include one the monorepo recorded before, because a signal dropped or renamed it, the run records the new set and reports the change as the failed task record_components, naming the components it dropped and the ones it now records. A pipeline stage, image repository or registry mapping key that names a dropped component builds nothing until it is renamed. A declaration of one component at the repository root is a single-app application, and the component takes the repository’s name.

A declaration Ankra cannot honour

The block is validated on its own and is refused as a whole, never partly applied. Ankra refuses it when:
  • components is not a list, or is an empty list (remove the key instead to let Ankra infer)
  • an entry is not a mapping, has no name, or has a key other than name, subdir, app_subdir, dockerfile, container_port and port
  • a name is not lower-case letters and digits joined by hyphens or periods
  • two entries share a name, or build from the same subdir
  • an entry sets both subdir and app_subdir, or both container_port and port, to different values (the same value in both is accepted)
  • subdir, app_subdir or dockerfile is not a single path, such as a list or a mapping
  • a path is absolute or leaves the repository with ..
  • a port is not a number from 1 to 65535
Ankra reports the first problem it finds, so a block with several problems shows the next one once the first is fixed. A refused declaration is reported as the failed setup task read_declared_components, with the reason, in the application’s jobs. When the application already records components, the run keeps them rather than inferring new ones over a declaration it could not read; an application with none recorded has its components decided by the other signals, as if the block were absent. The deploy options are still read from the same file. Fix the block and reconcile the application. A successful read reports the same task as Using the 2 component(s) declared in .ankra/ankra.yaml: api, web. A declared dockerfile that the repository does not contain is reported rather than built, and Ankra does not generate a Dockerfile over it. When Ankra rewrites the descriptor, for example to change the generated options, it copies your components and health blocks back exactly as you wrote them, refused or not.

Declared components and the pipeline

Each declared component gets its own build in .ankra/pipeline.yaml, attributed by its build-<component> stage name or by build.component. ankra pipeline validate reports two kind: build stages that publish to the same repository as a fatal pipeline_build_component: finding when both always run, because each run’s commit tag would be overwritten by whichever stage publishes last. When at least one of them runs only under a condition (if, when or matrix, or an on_failure or finally stage), the finding is a warning. See Validation.

Health

health declares the application’s liveness and readiness routes and a latency budget. The readiness gate, a platform setting, reads the readiness routes and the budget; liveness routes are kept on the application’s contract.
Ankra adds the declared routes to the health routes it finds in the source and treats each as the kind its list names, whatever the path looks like. A path listed twice in one list counts once. Where the readiness gate is switched off, nothing is probed. Ankra validates the block either way.

A health block Ankra cannot honour

The block is validated on its own and is refused as a whole, never partly applied. Ankra refuses it when:
  • health is empty, is not a mapping, or declares no route and no budget
  • liveness or readiness is not a list, or one of its entries is not a path
  • a path is empty, does not start with a single / (a relative path or a URL), contains whitespace, or contains any of { } [ ] * : < >, the marks of a template rather than a single path
  • one path is in both liveness and readiness
  • latency_budget_ms is not a whole number of milliseconds, is zero or less, or is over 5000
Ankra reports the first problem it finds. Keys other than liveness, readiness and latency_budget_ms inside the block are ignored. A refused block declares nothing: the health routes Ankra finds in the source stand, and the deploy options and components are still read from the same file. The refusal is reported as a descriptor_health: finding when Ankra validates the file before a commit of its own (see Validation); an analysis run does not report it.

Validation

Before Ankra commits a descriptor itself, in the setup pull request or in a commit or pull request Ankra’s AI makes, it validates the file and refuses the commit on a problem. Every problem is fatal, and only the first one found is reported, under one of these keys: The same validation applies to a file directly under .ankra/ whose name ends in -ankra.yaml, such as .ankra/web-ankra.yaml, the per-component descriptor of a multi-app setup. An analysis run reads only .ankra/ankra.yaml.

Applications

How Ankra analyses a repository, generates its packaging and deploys it.

pipeline.yaml reference

Every key of the pipeline definition that sits beside the descriptor.