Applications connect to GitHub repositories and use a GitHub credential. By default the generated CI/CD pipeline pushes the container image to your organisation’s private Ankra registry; if you already run your own registry, declare it and Ankra publishes to and reads from it instead.
Watch a GitHub repository go from its repo page to a running app on its own address.
How it works
1
Connect a repository
Applications → Add an application opens What are you shipping?. Choose a Repository connection (or Connect GitHub first), find and pick the Repository, then give the Application name and pick the Branch from the repository’s own branch list.
2
Analyze and generate
Ankra inspects the repository, detects the language and framework, and generates the artifacts it needs: a Dockerfile, Kubernetes manifests, and a CI/CD workflow.
3
Merge the pull request
The pull request runs its own checks first: it builds the image, scans it and runs the security gate. It stays a draft, which GitHub will not merge, until they pass, and then Ankra marks it ready for review; if you run the AI review, it skips the draft until then unless Review drafts is on. Review and merge it. Merging activates the CI/CD pipeline in your repository. When they fail, Ankra fixes the pull request itself, and the PR shepherd keeps it moving until you merge it - or merges it for you, if you opt in. Beside CI that Ankra adopted, with no CI at all, or on a private repository whose GitHub plan has no drafts, it opens ready for review.
4
Build and publish
CI builds and pushes the container image to the organisation’s private Ankra registry. Ankra surfaces the image URL and scans the published image.
5
Deploy
Deploy the application onto a cluster. Ankra verifies that the image was published and tracks the rollout.
When setup stops before the pull request. In two cases Ankra opens no setup pull request and deploys nothing. The setup ends as failed, and the application’s error message says why:
- Nothing in the repository keeps running. When the analysis finds only a program that runs once and exits, or nothing that runs at all, the message starts “Ankra did not set this repository up as an always-on application” and ends “Add a program that keeps running and listens on a port, then run setup again.”
- Nothing can be built. When there is no Dockerfile in the repository, on an open setup branch or among the files Ankra generated, the failed
setup_stoppedtask says what Ankra found and what it could not write. Add a Dockerfile and run setup again.
.ankra/manifests/, or whose own CI already publishes an image, still gets its setup pull request, with no build for anything that has no Dockerfile. So does a monorepo in which at least one component can be built.When your repository already has CI
If your repository already runs CI, Ankra reads it during analysis and works with it instead of adding a pipeline of its own. It reads GitHub Actions workflows,.gitlab-ci.yml, bitbucket-pipelines.yml and .circleci/config.yml, and notes for each one whether it runs tests, builds an image, pushes it (to which registry, tagged how), deploys, what triggers it and which runners it asks for.
The analysis says which of these it chose and why, and the setup pull request carries the same reasoning under Your existing CI.
When the image your CI pushes lives in a private registry, add a registry credential for it and name it with
ankra application registry set --credential so the cluster can pull the image.
Ankra also checks whether your CI actually starts. If the newest run of a workflow has waited in the queue for more than 20 minutes, the analysis reports it, names the runner labels the jobs ask for (for example a depot- or self-hosted label nothing is serving), and suggests switching runs-on to ubuntu-latest, connecting a runner for that label, or letting Ankra Pipelines run the build. Ankra never edits your workflow.
To build with Ankra Pipelines anyway, convert the application with ankra application pipeline convert. A repository that already commits .ankra/pipeline.yaml keeps building with it.
When the setup pull request does not pass its checks
A repository can already carry problems Ankra did not put there - most often dependencies with known security issues, which the security gate refuses to publish. The setup pull request then fails its own checks, and you do not have to fix it yourself:- Ankra AI fixes it on the same pull request. An agent reads the run, commits a fix to the setup branch (for vulnerable dependencies: newer releases, overrides, a regenerated lockfile) and watches the checks until they pass. It never opens a second pull request and never touches your default branch.
- The pull request says what is happening. Ankra’s status comment explains in plain words what stopped the run and that Ankra AI is fixing it, and the application’s Go live page shows the same. Merge once the checks are green.
- You can turn it off. Automatic build fixing is on for every application by default. Turn it off for one application, or pause Ankra’s autonomous actions, and the pull request only gets the explanation and a Fix with Ankra link.
When a build on your branch fails
A failed build on the application’s tracked branch dispatches the same agent. What it may do depends on the repository’s CI/CD lane on the application’s AI tab:When a pull request fails its checks
On Ankra Pipelines, a failed build, image gate orrun step (your tests, for example) on any pull request from a branch of your repository, not only the setup pull request, is fixed on that pull request:
- The fix lands on the pull request’s own branch. An agent commits it to the head branch and watches the run that commit starts. It opens no second pull request and changes only what the failure needs. For an image gate the agent is handed each vulnerable package with the releases that fix it, and moves it to at least the highest.
- A conflict with the base branch is resolved the same way. The status comment opens “This pull request conflicts with” and names the base. The agent merges the base into the head with a merge commit, resolving every file both sides changed, and the run of that merge commit is its check. Nothing is ever merged into your default branch.
- When the AI allowance is used up, on Ankra’s own models with no key of your own, the status comment says the fix is queued and starts by itself when the allowance resets on the 1st of the month, or as soon as an organisation owner adds the organisation’s own model key under Organisation settings, AI provider; if billing has paused AI, it names that instead.
- Without AI, vulnerable Python packages are still upgraded. When the image gate blocked the run and the fix has to wait, Ankra moves each package a lock file pins to a release that fixes it, checked against the packages’ own requirements, commits that to the pull request on GitHub, and leaves the rest for the allowance.
- The same switches hold it: automatic build fixing turned off for the application, Ankra’s autonomous actions paused, or an environment of the application set to You run it.
The PR shepherd
Ankra watches the pull requests it opens in your repository - the setup pull request, and any portability pull request a Launch Plan opens - and drives each one to a state you can merge. You see it as an Ankra PR shepherd check on the pull request’s latest commit. Its summary says where the pull request stands - waiting, ready, needs a person, or merged - and why, and it is updated as things change. What the shepherd does on its own:- Your CI never starts. When no CI check has started on the pull request after about 20 minutes - no runner picks the job up, or the Ankra agent on your CI cluster cannot run pipeline steps - Ankra starts a full Ankra pipeline run on the pull request’s head, builds it on Ankra’s builders and runs a proof of the application, so the pull request still gets an answer.
- The pull request falls behind its base branch. Ankra merges the base branch into its own branch with a merge commit - never a force-push or a rebase. It waits until the head has sat for about 6 hours, or does it straight away when merging is opted in (below).
- The pull request conflicts with its base branch. Ankra resolves the conflict only when every file in the pull request is one Ankra owns: the Dockerfile,
.dockerignore, the.ankra/directory and the generated build workflow. Your own files are kept exactly as the base branch has them, and a conflict that touches them is left for you. - A check fails. When the pull request only changes Ankra’s own files, Ankra AI fixes it on the same branch, up to 3 times, then reports it for a person. A failure in a pull request that changes your files is reported, never “fixed”.
- The proof of the head never gives an answer. Where your organisation has a staging cluster, a proof still queued 20 minutes after Ankra queued it, or one that ended not proven, is a dead end: once nothing else is pending, the check reads Needs a person, names the proof and its reason, and Ankra does not merge. The shepherd keeps looking every 15 minutes, so a proof that passes later turns it Ready to merge.
Merging
Ankra merges a pull request only when all of these hold:- merging is opted in for the application (below);
- every check on the head has finished green, and the proof of the application passed;
- GitHub reports the pull request mergeable. Branch protection is always honoured, never worked around.
Opting in to merging
Merging is off by default. Two settings decide it:- The organisation’s setting,
auto_merge_setup_pull_requestsonPUT /org/applications/settings(orankra_application_settingsin Terraform). Only organisation admins can change it. - The application’s own setting, which overrides the organisation’s: on for this application, off for this application, or follow the organisation (the default). Read it with
GET /org/applications/{application_id}/auto-merge-setup-pull-requestsand change it withPUTand a body of{"enabled": true},{"enabled": false}, or{"enabled": null}to follow the organisation again. Only organisation admins can change it. The answer carries the application’s own value, the organisation’s, and theeffectiveone Ankra acts on.
Building on Ankra’s builders
The flow above puts the first image behind a merged pull request: until the generated workflow is on your default branch, your CI has nothing to run, and nothing to publish. Ankra can also build the image itself, on its own builders, with no workflow in the repository at all. Ankra clones the commit, resolves a recipe for it, builds it, and pushes the image to the same registry the application publishes to. The recipe is the first of these that fits:- The repository’s own
Dockerfile- used as-is. - A generated Dockerfile - the one Ankra wrote for this application.
- Buildpacks - when there is no Dockerfile to use.
--commit takes a full 40- or 64-character commit sha. The queue deduplicates on the string it is given, so an abbreviation would be a second key for the same commit and would build it twice. Asking twice for one commit joins a single build rather than racing two, and the answer’s already_requested says when that happened.Following a build
A request is not yet a build.start answers with a request id immediately; the build itself is created when a builder claims the request. So there are two things to read:
ankra application build start --wait walks both steps for you and exits non-zero if the build failed, which makes it usable as a pipeline gate. Watching the build list instead is a trap: a previous failed build of the same commit is still the newest one for that commit, so it would report an old failure as your build’s result.
Waiting for a builder
Ankra’s builders are one pool that every organisation shares. Your organisation runs at most three builds on it at a time, so a burst of builds from one organisation - onboarding a repository with many components, say - cannot hold every builder while others wait. Requests beyond three staypending, in the order they were made, and the next one starts as soon as one of your running builds finishes. A pending request is waiting its turn, not failing: it keeps its request id, and --wait keeps following it.
What a failure means
A failed build carries anerror_class that says whose failure it was:
The last three are platform-side and are already visible to Ankra without anyone reporting them.
This replaces the image build, not the whole generated pipeline. That workflow also runs a Semgrep scan, and packages a Helm chart for applications that publish one. If you plan to retire the workflow entirely, decide where those two go first.
The application workspace
An application opens as a workspace at/next/applications/<application-id>: the application’s own menu takes the sidebar’s place, in the order the work happens. Each section is a view of that page, named in the address with ?view=, and a view’s own tabs with §ion=. A link that uses a view’s older name still opens the view it meant. The table describes the sections this page refers to; The application page lists every row of the menu in order. The last column gives each section’s address, after /next/applications/<application-id>; Portal URLs lists them in full.
The menu carries one mark: Environments reads as needing attention while the environment in view has failed or is degraded, or its rollout is stuck, and while the Deploy group is closed, its heading carries the mark.
The Applications list groups applications under Needs you, Ankra is on it, Live, Parked, Not deployed yet and Couldn’t check, with a count of each under the title. You can search by name or repository, and filter by status, environment and language.
Remove a deployment from one cluster
Removing takes the application off one cluster and leaves the application, and everywhere else it runs, in place. Ankra uninstalls its workloads, services and configuration in that namespace, and deletes the installation record once the uninstall has been handed to the cluster; the place reads as removing in the deployments read until the cluster has taken it down. A deployment that holds data (a CloudNativePG database, a persistent volume claim or a StatefulSet’s volume claims in the application’s manifests) is removed only when a complete restore point of its stack, taken in the last 24 hours, covers that data. An add-on among what it would remove, such as a wizard stack’s database add-on, is never covered, because Ankra cannot see its volumes from its definition, and neither is a manifest Ankra cannot read. Otherwise nothing is removed, and the removal fails with a reason naming the data and the two ways forward: take a restore point and remove again within a day, or remove those members from the stack yourself on the cluster’s Stacks page. The application itself, with its settings, secrets, published images and release history, its other deployments, the add-ons on that cluster other workloads may use, and the cluster itself all stay, so you can deploy there again from Environments → Deploy a version. To stop a deployment for a while without losing anything, park it instead; to take the application out of Ankra everywhere, delete it. Its home is Settings → Park or remove (?view=settings§ion=runtime). The environment in view lists where the application runs, each place with Park (or Wake) and Remove; below it are the places that run the application outside every environment, a stack the deploy wizard made or an add-on carrying its chart in a stack the application did not create, which cannot be parked, only removed. Where it runs offers Uninstall on an environment’s place too, behind the same review, and links everything else to Park or remove. Removing an installation or a wizard stack needs permission to deploy the application (applications.deploy); an add-on’s removal needs stacks.delete on that cluster instead, as below.
The review names what goes and what stays before anything happens and, opened from Park or remove on an environment’s place that is not parked, offers Park instead. Removing an installation takes one deliberate press, except when the deployment serves a production environment, is the only place the application runs, or Ankra could not read where else it runs or which environment it serves: then the cluster’s name has to be typed. The platform answers as soon as it has accepted the teardown, not when it is done: the installation reads removing until the teardown job has handed the uninstall to the cluster and deletes it, or failed with its reason, which is also what ankra application installations shows. Park or remove lists it under Being removed, reading every few seconds for the first two minutes and every half minute after that, and says what became of a removal asked for there once it settles: removed, naming any stacks left in place because other workloads may use them, or that it did not finish, with the platform’s reason when it gave one, in which case the deployment is listed again and can be removed again once the cause is fixed. A deployment that holds data with no fresh restore point fails this way, with the reason above. A second removal of the same deployment is refused as Already being removed (409), a deployment no longer on that cluster as Nothing to remove, and while a removal runs a deploy to the same cluster and namespace is refused with 409.
An application deployed with the deploy wizard has no installation: it runs as a stack, named by cluster and stack name. Ankra removes only a stack it can show runs this application, from push to deploy’s record or from the image it runs; one it cannot attribute is left in place as This stack stays, because it may be a shared operator, and goes from the cluster’s Stacks page if it is no longer needed. The other stacks the same deploy created stay and are named in the answer, and the removal is followed through its undeploy_application job, which ankra application jobs lists.
An add-on that carries the application’s chart in a stack the application did not create is removed from that stack through the cluster’s add-on uninstall. The review says whose stack it is, that Ankra commits the change to the cluster’s Git repository and that the rest of the stack stays; the cluster’s name is always asked for, and it needs permission to delete stacks on that cluster (stacks.delete). An add-on that belongs to a deployment of this application is refused as Remove it as a deployment: remove that deployment instead, so its record goes with it. A cluster Ankra cannot reach that is not stopped either cannot take the removal (That cluster isn’t reachable), and a change its Git repository did not take reads The change wasn’t committed.
On a stopped cluster an add-on’s removal is recorded now: Ankra takes the add-on out of the stack and commits the change now, or at the cluster’s next sync when its repository has changes Ankra has not taken in yet, and uninstalls it when the cluster next starts, so you do not need to start the cluster for it. Park or remove lists it under Waiting for the cluster to start, with Keep add-on (permission to change stacks on that cluster, stacks.write) to take the removal back while it waits; a removal the cluster cannot hold until it starts is refused as This removal can’t wait for the cluster. Only an add-on’s removal is held for the start: an installation or a stack removed from a stopped cluster reads Being removed, and Where it runs gives no time for it.
A place whose removal is recorded is no longer where the application runs, whatever its cluster still carries. The deployments read answers it in removal_deployments, apart from deployments, without a health or sync verdict, and the cluster and health counters are summed over deployments alone. Where it runs lists these places under Being removed, with when the removal finishes as its status, and no version: for a cluster named staging, Removed when staging starts for a removal waiting for the stopped cluster, Finishes when staging is back online for one on an unreachable cluster, and Being removed otherwise. A place listed under Being removed is never Needs attention, and an application whose only places are being removed no longer reads Nothing is running anywhere yet.
Over the API, POST /api/v1/org/applications/{application_id}/deployments/remove takes cluster_id with namespace for an installation or stack_name for a wizard stack, not both, and answers 202 with the cluster_id, the namespace (empty for a stack) and a stack’s stack_name, an installation’s installation_id, any retained_stacks, the teardown’s operation_id and status removing. ankra application remove <application> --cluster <cluster> does the same and asks first (--yes skips the prompt): --namespace only when the application runs in more than one namespace on that cluster, --stack for a deploy-wizard deployment, -o json or -o yaml for the answer. Ankra’s AI and MCP clients have remove_application_deployment, which Ankra’s chat runs only after you confirm it (an MCP client with mcp:write runs it directly), with list_application_installations to find the cluster and namespace and park_application_deployment as the reversible stop; see the MCP Tool Reference.
What Ankra tracks
For each application you see:- State and analysis status - where the application is in the connect/analyze/generate/build lifecycle, with an error message if something needs attention.
- Repository - owner, name, branch, and URL.
- Components - the repository’s deployable apps. An ordinary repository has one; a monorepo has one per app.
- Artifacts - the private container image URL and the latest published build, per component.
- Pull request - a link to the generated PR.
- Jobs - the underlying platform jobs for the application, so you can follow analysis and generation as it runs.
Monorepos
A repository that builds more than one deployable app is onboarded as a monorepo: Ankra records one component per app, and each component gets its own packaging and its own image.
Ankra decides the components from, in order: the
components block of the repository’s .ankra/ankra.yaml, when it declares one; the per-component workflows the repository already carries (so re-running analysis never renames a component and orphans the images it has published), the apps the analysis proposed, then the repository’s structure - two or more Dockerfiles in subdirectories and no Dockerfile at the root, or a workspace marker (nx.json, turbo.json, lerna.json, pnpm-workspace.yaml, go.work) plus two or more subdirectories with their own dependency manifest. Without a declaration, a Dockerfile at the repository root always means a single app, whatever else the repository contains.
The AI proposal and structural detection can add components to a monorepo but never leave it with fewer than it records: a run whose inference finds fewer keeps the recorded ones. Only a declaration, or two or more of Ankra’s per-component build workflows for fewer components than the record, can shrink it, and a run that drops or renames a recorded component records the new set and reports the change as the failed task record_components. A repository whose layout inference misreads, such as an API built from deploy/docker/Dockerfile at the root beside a web app in web/, declares its components in .ankra/ankra.yaml, and the declaration is also how you remove one.
Build state, published images, deploys, demos, and container scanning are all reported per component, so an application whose API component built and whose frontend did not says exactly that.
Using your own registry
An application publishes to your organisation’s private Ankra registry unless you say otherwise. If you already operate a registry - the same Harbor whose OCI charts Ankra indexes, for instance - declare it on the application and Ankra publishes there, reads the published tags back from there, and pulls from there. Declare it on an existing application from Settings → Registry, from the CLI, or withimage_registry when you create the application. The settings panel also reports the host and project the declaration resolved to and the image repository each component is expected to publish to, so you can compare them against where your builds actually push.
Ankra does not mint robots for a registry you operate unless you hand it the keys. With a declared registry and no
admin_credential_name, setup names the two Actions secrets the workflow reads and leaves them to you, rather than writing a credential Ankra happens to hold over a push robot you administer. Publish readiness reports whether those secrets exist and names them. Name an admin_credential_name to have Ankra mint a push robot for the application there (Robot accounts), or set manage_actions_secrets: true to have it write the declared credential into them instead.
An application is bound to the GitHub credential it was created with; its App installation must reach the repository for builds, deploys and Actions secrets. Move an application onto another credential of the organisation with
ankra application credential set <application-id> --credential <name> (GET/PUT /api/v1/org/applications/{application_id}/repository-credential); the answer reports whether the new binding resolves to an installation.On a monorepo, a component may declare its own
image_registry to publish into a different project of the same registry - useful when each app has its own robot accounts and retention rules. A component’s declaration wins over the application’s; the application’s applies to every component that declares none.Robot accounts
Every application gets a registry robot account of its own: a push+pull robot namedrobot$<project>+app-<application-id> on the project it publishes to, stored as the platform-managed registry credential ankra-harbor-app-<application-id> and written into the repository’s Actions secrets as the login the build workflow uses. Nothing else shares that login, so a leaked repository secret is rotated or revoked for that one application, and a deleted application takes its robot with it.
- On your organisation’s Ankra registry the robot is minted automatically when the application is set up, and again whenever the application is reconciled. Applications onboarded before robots existed get one when the application is next reconciled, or from Settings → Registry with Set up publishing login.
- On a registry you operate, Ankra mints one only with a credential that may: set
admin_credential_nameto a registry credential with project administrator rights on the declared project (in Harbor, a project admin user, or a robot granted the robot-account permissions). Without it Ankra never touches your robots; publish readiness names the field.
/api/v1/org/applications/{application_id}/registry-robot (GET, POST with {"rotate": true|false}, DELETE). The robot’s credential appears in your organisation’s registry credentials as managed by Ankra; it cannot be edited or deleted there, only through the application.
Security scanning
Applications include code and container security insights, so vulnerabilities surface alongside the build rather than in a separate tool. The Security section reads the way the Security Center reads a fleet finding - risk first, ranked by exploitability - in eight views:
Every finding row opens a sheet with severity, CVSS, EPSS (as
EPSS 94% · top 1%), the CISA KEV entry - date added, due date, ransomware use and required action - the fix, and a link to the platform’s own advisory page for the CVE. Exploitability reads Unknown until the KEV catalog has synced; absent is never read as not exploited.
On a monorepo, the image tags and the scanned image reference follow the component you select; code and IaC findings cover the whole repository, because that is where those scanners run. Pair this with AI Insights for proactive analysis.
Preview demos
Before you merge, you can spin up a throwaway demo of a pull request or branch build to see it running. In the portal these live in the application’s Previews section, which calls each one a preview; the CLI and API keep thedemo name. Each demo is deployed into its own isolated namespace (ankra-demo-pr-<n> or ankra-demo-br-<branch>) on the organisation’s staging cluster, PodSecurity-hardened and quota-bounded, and is automatically torn down when its TTL expires - so it can never affect existing workloads.
1
Configure a staging cluster
An admin sets the organisation’s Staging cluster under Ankra AI → AI workspaces. Optionally set a Preview domain (with an Ingress class and TLS secret) there too - this is what gives demos a public URL.
2
Deploy a demo
Deploy a branch or PR demo from the application’s Previews section, from the CLI, or by asking the AI assistant. The demo pulls the image tag the PR/branch build pushed.
3
Open the preview
When a public host is available, Ankra returns a preview URL you can open directly. Otherwise the demo stays reachable in-cluster (service DNS + a
kubectl port-forward command).The preview URL
Ankra resolves the demo’s public hostname automatically, and every surface (portal, CLI, MCP, and automatic PR previews) uses the same rule:- An organisation demo base domain, if configured, wins outright - the host is
<namespace>.<demo-base-domain>, served with your configured ingress class and TLS secret. - Otherwise, the staging cluster’s own delegated DNS zone, but only when that zone is active - giving
<namespace>.<cluster-id>.<org-id>.<ankra-domain>, a hostname theexternal-dnsrunning on that cluster can resolve. When the cluster also carries the Ankra networking stack, the demo’s ingress requests a Let’s Encrypt certificate from itsletsencrypt-prodissuer automatically, so the preview URL is served over https. - Otherwise the demo stays in-cluster-only - no ingress is created, and you reach it with the returned service DNS name and
kubectl port-forward.
A demo only gets a resolvable public URL when the organisation has a demo base domain configured or the staging cluster has an active Ankra DNS zone. Without either, the demo still deploys - it just stays in-cluster-only.
ankra.cc by default. An organisation can register its own custom domain - dedicated to that organisation alone - in the Custom Ankra domain field under Ankra AI → AI workspaces, or from the CLI with ankra org domain set <domain>. The domain must be a bare domain the organisation owns, its NS records must already point at Ankra’s nameservers (the ones serving ankra.cc), and no other organisation may hold it.
With a custom domain registered, the external-dns Ankra runs on each of the organisation’s clusters is scoped to the whole domain, not just that cluster’s delegated <cluster-id>.<org-id>.<domain> zone. An Ingress on any hostname under the domain - a top-level name like app.example.com included - is published automatically by the cluster serving it. On the shared ankra.cc root the scope stays the cluster’s own delegated zone: names directly under ankra.cc are allocated by the platform, and one organisation’s cluster must never be able to write another’s.
Zones already provisioned keep the domain they were minted under, so the switch is refused while any cluster DNS zone or DNS record still lives under the old domain. The refusal names exactly what is blocking it - the portal lists the cluster domains and records beside the field, and ankra org domain set prints the same list - so the migration is a checklist rather than a guess:
1
Inventory what is under the current root
ankra org dns zones lists every cluster domain in the organisation with its state; ankra org dns list lists the DNS records. Both are reads. In the portal the same two lists are on Infrastructure → Domains: the cluster domains under Cluster names, and the records on the organisation’s Ankra domain.2
Destroy any playground environment
A playground publishes a wildcard DNS record in the organisation’s zone, and that record is reconciled - the platform writes it again on its next pass over a ready environment, so deleting it in the next step will not clear it. Destroy the environment instead:
ankra cluster playground destroy <cluster_id>. The refusal names any playground that is still holding a record.3
Remove each cluster domain
ankra cluster domain <cluster> --remove (or DELETE /api/v1/clusters/{cluster_id}/dns-zone, or Take the name away on the cluster’s row under Cluster names in the portal) hands the zone to Ankra for teardown.The removal is held: nothing re-creates the zone until you ask for it back in the last step - not the external-dns Ankra runs on that cluster, and not the discovery that mints zones for clusters that have none. ankra cluster domain <cluster> reports Opted out: yes for as long as the hold stands, so a domain that is gone is distinguishable from one that is between reconciler passes.4
Delete the DNS records
ankra org dns delete <record>, or delete them from the records list on Infrastructure → Domains. These are the records you created; anything the platform publishes is listed separately in the refusal, with what to remove instead.5
Register the new domain
ankra org domain set example.com, or save the Custom Ankra domain field. Ankra tears the organisation zone down and re-creates it under the new domain automatically.6
Re-enable the cluster domains
ankra cluster domain <cluster> --enable withdraws the hold and re-creates each cluster’s zone under the new root, and the cluster’s external-dns picks up the new zone on its next cloud-provider stack pass. Every cluster you removed in step 3 needs this, the staging cluster included.ankra cluster domain <cluster> on its own is a read: it reports the cluster’s domain, or state none when it has none, and never creates a zone. Creating one is the explicit --enable. (Before CLI v0.13.0 the bare command created a zone, which meant checking a cluster’s domain could add a blocker to this very migration.)What a root-domain switch does and does not touch
Two questions decide whether the switch is safe to attempt on a domain that is already in use. Both have short answers. Ankra touches only the records it creates in the domain you register. Registeringexample.com adopts it as the organisation’s zone apex, with each cluster’s own <cluster-id>.example.com subzone under it, and the external-dns Ankra installs on every cluster is scoped to the whole domain so it can publish top-level names like app.example.com. Each controller runs with its own record ownership (--txt-owner-id), so it creates, updates and deletes only the records that exist because of an Ingress on its cluster: records you already publish at the apex or under any other name in example.com are never read, written or deleted - not by the switch, and not by anything Ankra runs afterwards.
A switch never re-labels a zone. Zone labels are derived from the organisation and cluster ids, so they are the same under any root: a cluster that was axmndle4sl.<org>.ankra.cc becomes axmndle4sl.<org>.example.com. The label is also what Ankra passes as external-dns’s --txt-owner-id, and what any GitOps path built from a cluster domain embeds - so the TXT ownership registry stays matched to its records across the switch, and the paths do not move. --enable re-creating a zone preserves the label for the same reason.
Serving a zone in your own DNS account from every cluster
A custom Ankra domain has to be hosted in Ankra’s own DNS account, because Ankra mints the per-cluster credentials for it. A zone you keep in your own DNS provider account is different: Ankra cannot mint anything there, so theexternal-dns it installs drops Ingress hostnames on that zone silently (the sync logs All records are already up to date, because from its point of view there is nothing in scope), and cert-manager’s HTTP-01 challenge for such a hostname waits forever for a name that never resolves.
Declare the zone with a credential of your own instead, once, for the whole organisation:
external-dns for example.dev, rendered and reconciled by Ankra in a dedicated custom-dns stack, within about two minutes of the declaration or of the cluster coming up. An Ingress on chat.example.dev publishes from whichever cluster serves it, and the certificate follows once the name resolves. On a cluster with the Gateway API option, an HTTPRoute hostname on the zone publishes the same way, once the Gateway API CRDs are on the cluster. Each cluster’s controller is pinned to exactly that zone (--domain-filter) with its own record ownership, so it can never fight the controller Ankra runs for the cluster’s Ankra domain, another cluster’s controller, or records you publish in the zone yourself.
- The credential is the external-dns webhook provider URL including its token, for any provider that speaks the external-dns webhook protocol. It is written to the platform’s secret store on create and no read surface returns it; re-creating it under the same name re-points every cluster at once, which is how a rotated token rolls out. Its name is what
listshows. ankra cluster custom-dns-zones add <cluster> --zone <zone> --credential <name>declares the same thing for one cluster. A cluster’s own declaration of a zone takes precedence over the organisation’s on that cluster - the way to serve a zone with a different credential on one cluster - andankra cluster custom-dns-zones list <cluster>shows where each zone a cluster serves was declared (SOURCE=clusterororganisation).- A zone that overlaps the domain Ankra already serves for the organisation (its
<org-id>.<ankra-domain>zone, or the whole custom Ankra domain when one is registered) is refused: Ankra’s own controllers publish there already and cannot be told to stay off those names. A zone above the Ankra domain is accepted, and each cluster’s controller is told to leave the Ankra-served part alone. - A zone at Cloudflare needs no webhook: connect a scoped Cloudflare API token once with
ankra org cloudflare connect <name>and declare the zone with--cloudflare-credential <name>. Ankra checks with Cloudflare that the token reaches the zone and is not denied DNS edit there before the declaration is stored, and that controller runs upsert-only: it never changes or deletes a record someone else made. See Serve a Cloudflare zone from every cluster. - A domain in Avura needs no credential of your own: once the Avura workspace is connected to the organisation and the domain is shared with Ankra, declare it with
--credential avura. See use Avura domains with Ankra. ankra org custom-dns-zones remove --zone example.devwithdraws the declaration. Ankra tears down the controllers it rendered on every cluster that inherited the zone; clusters that declared it themselves keep theirs, and the zone’s records are yours and are left untouched.
GET/POST /api/v1/org/custom-dns-zones, DELETE /api/v1/org/custom-dns-zones/{zone}, and the per-cluster /api/v1/clusters/{cluster_id}/custom-dns-zones twins.
Deploying a demo
A demo deploys every component of the application by default. A single-app application runs its one image; a monorepo runs one pod per component - the frontend and the API of a two-app repository both come up, wired together, instead of half an application answering where the other half belonged. You can still deselect components or demo a single one.- Portal
- CLI
- AI / MCP
Open the application’s Previews section, choose Launch preview, pick a branch or enter a pull request number, and deploy. The dialog groups what to preview, its lifetime and environment, and the staging cluster, and lists the branch, image, lifetime, template, resources, cleanup and access in a summary before the launch button; a missing image or an offline staging agent is an explicit blocker. The section shows one card per active preview with its branch or commit, component, image, expiry, access and cluster. Each preview links to its own detail page - live provisioning progress read from the staging cluster, the namespace’s bill of materials with manifests (grouped per component), Kubernetes events, and pod logs, plus the preview URL or port-forward command to reach it. On a monorepo the launch dialog lists every component with its own build status and tag, lets you include or exclude each, and marks the web entry - the component that owns the demo URL.
Monorepo demos: every component, one URL
A monorepo demo deploys each component as its own Deployment and Service inside the demo namespace, and the demo only reports ready once every component accepts connections:-
The web entry owns the demo URL. Ankra picks the frontend-shaped component (a name or directory like
frontend,web,ui,portal) as the entry serving/on the demo host; you can move the entry in the launch dialog or withentry_componenton the API. -
API components share the host under a path. The single API-shaped component (
api,backend,server) is published under/apion the same demo host, routed straight to its Service - so a browser calling/api/...reaches the API even when the frontend’s own proxy target was baked for another environment. Override per component withingress_path. -
Save the routing when the guess is wrong. The entry and the
/apipath above are heuristics, and the lanes with no human in the loop - the automatic PR previews and the MCP demo tools - have no launch dialog to correct them in. Declare the routing once in the demo configuration and every lane follows it:A declaration is authoritative: the/apiguess stops running, so a component you leave out ofcomponentsstays reachable in-cluster only rather than picking up a path it never asked for. Per-launchingress_pathoverrides still win over the declaration. Clear it with"routing": nullto return every lane to the heuristics. -
Components reach each other by name. Every component’s Service is named after it, so in-namespace URLs like
http://crm-api:8090resolve. Env values can also use placeholders that resolve at deploy time:
The saved migration command runs once per deploy, inside the image of the component that owns the schema (the primary component - usually the backend). Demo environment defaults and the throwaway database are shared by every component of the demo.
Existing demos and single-app applications are unaffected: a demo recorded before multi-component support (or of an application with one component) keeps exactly the previous single-pod shape.
Environment variables and a throwaway database
Most real applications need configuration to boot - a database name, an API key, an SMTP host. Demos support both per-application defaults and per-launch overrides, so any codebase can run as a demo without changes:- Defaults are the application’s environment template, under Previews (Preview settings), which separates the disposable dependencies each preview gets from the shared services it points at and labels every generated value with the dependency it comes from. Every demo of the application inherits them - manual launches, CLI/MCP deploys, and the automatic PR previews.
- Overrides are set per launch in the Environment & database section of the launch dialog (or via the
envargument ofdeploy_pr_demo). Overrides win by name.
The throwaway database is ephemeral by design: it starts empty on every deploy and is wiped with the namespace. The database runs a pgvector-capable Postgres, so migrations using
CREATE EXTENSION vector work. .url and .password references are always delivered through a Kubernetes Secret, never as plain env text.migrate_command) - for example pnpm run db:migrate or alembic upgrade head. It runs inside your application image (sh -c) as an init container, after the database accepts connections and with the same environment the app sees, so a fresh demo database provisions its schema before the first request. Because every deploy starts the database empty, the command re-runs on every deploy - write migrations to be idempotent (every standard migration tool is).
The command runs with your image’s
WORKDIR as the working directory and on PYTHONPATH. Python puts the script’s directory on sys.path, not the working directory, so a migration entrypoint that is a script rather than a console script - python scripts/bootstrap_database.py - could not import the application package sitting beside it and died at import with ModuleNotFoundError. Setting PYTHONPATH yourself in the command still wins.database_extensions (for example ["vector"]) and the demo database creates them at initdb, before your migrations run.
Ankra detects both automatically when it analyses a repository: a Postgres client dependency, an ORM configuration, or a composed database marks the application as database-needing, its referenced connection variables are wired to the ${{ ankra.demo_database.* }} placeholders, and a recognised migration script becomes the migration command - so the first demo of a database-backed application works without any manual configuration. Detection only ever seeds an application that has no demo configuration yet; it never overwrites what you or the pre-setup agent saved.
The demo container port
The demo’s readiness probe, Service, and preview route all target one container port, resolved in this order: the component’s recorded port, the generated runtime Dockerfile’sEXPOSE, the generated Deployment manifest’s containerPort, the analysed target_port parameter, and only then the platform default. The launch dialog shows the resolved port and where it came from; a port you did not edit is left to the platform to resolve.
When the resolved port is still wrong - stale analysis, a hand-edited Dockerfile - the platform corrects itself at runtime: a demo whose container runs cleanly but never accepts connections has its logs read for the port the server actually announces (Accepting connections at…, Listening on…, and the other common startup banners). If the evidence is unambiguous, the demo is repointed at the announced port on the fly, the correction is recorded on the application so the next launch resolves it statically, and the demo detail page shows the correction. Ambiguous evidence never auto-corrects; it flows into the failure message (“Nothing accepted connections on port 3000. The container’s logs say it listens on port 8001.”) and dispatches the pre-setup agent instead.
Automatic pre-setup when a demo crashes
An image that validates its environment on boot - refusing to start without a database URL, an auth secret, an API key - crash-loops when demoed with no configuration. Ankra now detects this and fixes it with an agent:- When a demo fails with a startup crash (CrashLoopBackOff or a container configuration error), a failed migration command, or a port-evidence timeout (the container announced a different port than the demo probed), Ankra dispatches a one-shot pre-setup agent for it automatically. The run appears on the AI agents page like any other mission.
- The agent reads the crashed container’s logs, works out which environment variables the application demands, and generates a pre-setup: missing database URLs become
${{ ankra.demo_database.* }}references with the throwaway Postgres enabled, secrets get fresh random values, and mode flags get the value that avoids external side effects. - It saves the pre-setup as the application’s demo defaults - so every future demo inherits it - and redeploys the failed demo to prove it boots.
CREATE EXTENSION failures. It never weakens the application’s own validation, never reuses values found in logs, and merges with existing demo settings rather than replacing what you configured. Dispatch is bounded to one run per demo per day; image-pull failures and provisioning timeouts never dispatch (no environment can fix those). You can also trigger it on demand with POST /org/applications/{application_id}/demos/{workspace_id}/fix, or just ask the AI assistant to fix the failed demo - the chat has the same get_demo_diagnostics, update_application_demo_config, and redeploy_demo tools the mission uses.
Managing applications
Which Ankra AI lanes run on the application’s repository - the pull request review, the organisation skills review, the automatic preview URL - is set per application under Settings → Who runs it, in the On your pull requests card. See Application AI settings.
Prerequisites
1
Connect GitHub
Add a GitHub credential with access to the application’s repository. The Ankra GitHub App needs permission to open pull requests, commit workflow files, and manage Actions secrets. Ankra installs the Ankra registry credentials on the repository automatically; for your own registry you set the login secrets yourself.
API
Applications are available over the API for CLI and scripted use, under/api/v1/org/applications (bearer-token authenticated) - create, list, inspect, retry, reconcile, and delete. See the API Reference for endpoints and schemas.
The same lifecycle is available through Ankra’s AI and MCP clients - connect, deploy, retry, reconcile, and delete applications, and follow their CI workflow runs - see the MCP Tool Reference.
See the CI/CD Pipeline guide for how the generated pipeline fits into GitOps.