Skip to main content
A branch preview runs a branch’s already-built container image in its own temporary namespace on your organisation’s staging cluster, and Ankra removes it when its lifetime ends. Use it to show work in progress, reproduce a bug against one build, or hand a reviewer a live address instead of a screenshot. Pull requests get previews automatically once you turn them on. This guide covers the manual path: New preview in an application’s Previews view, and the same step in the CLI and MCP.

Before you start

  • A connected application. The branch must belong to an application whose setup has run.
  • A staging cluster for previews. Someone whose role holds ai.manage (the owner and admin roles do) chooses it under Ankra AI → AI workspaces, in Where workspaces and previews run → Staging cluster (/next/organisation/ai-workspaces#staging). Without one, the Previews view reads Choose where previews run. and New preview is disabled. The cluster’s agent must be online too: otherwise the view reads The preview cluster is offline.
  • A role that can deploy. Starting and stopping previews needs the applications.deploy permission. Without it the view says “Only people who can deploy can start previews. Ask an admin.”
  • A published build of the branch. A preview deploys an image; it does not build one. See Which image a preview finds.

Start a preview

1

Open Previews

Go to Applications → <your application> → Previews (/next/applications/<application-id>?view=previews).Check: beside the Cluster online badge you see the staging cluster’s name and Maximum lifetime in hours. That maximum is the cap your role has, set under Ankra AI → AI workspaces by someone whose role holds ai.manage.
2

Choose the branch and lifetime

Select New preview. In the New preview dialog, pick the Branch and set Lifetime (hours). The lifetime starts at the organisation’s default and cannot go above your maximum.Check: as soon as you pick a branch, Ankra checks the registry and a note under the fields reads Published image: <tag>. If it reads anything else, see No published image for the branch.
3

Review and launch

Select Review preview. The review lists the Branch, the Destination cluster, the Lifetime and the Published image. Select Launch preview.Check: the dialog reads Preview launch accepted. Select Done. A card for the branch appears under Previews with its status.
The preview starts from the application’s preview configuration: its variables, login, database and what it is built from. You set those once, under Set what every preview starts with, not in this dialog.

Verify

Each preview card shows Started, Version (the image it runs), Ends automatically and Data (Throwaway database or Application defaults). When the preview is ready and its address is confirmed, the card offers Open preview. Select it and your branch’s build opens in a new tab. From the CLI, list the application’s previews and read their addresses:

Which image a preview finds

Ankra looks in the application’s registry repository for these tags, in this order, and deploys the first one it finds:
  1. sha-<7>: the first seven characters of the branch’s head commit, the only tag that is provably this head’s build.
  2. For each open pull request from the branch, sha-<7> of its merge commit, then pr-<number>.
  3. The branch name, with every character other than letters, digits, ., _ and - replaced by - (feature/login becomes feature-login).
A pull request tag is built from merging the branch into its base, not from the branch head. What publishes these tags depends on what builds the application (see Ship your app): So a preview of any branch other than the tracked one needs an image from somewhere else. Build the branch’s head on Ankra platform builders:
Or push a sha-<7> tag from your own CI.

Set what every preview starts with

Everything a preview needs beside the image is configured once per application, under Applications → your application → Settings → Deploys (/next/applications/<application-id>?view=settings&section=deploys). Changing it needs a role that can configure the application. Existing previews keep what they were launched with; the settings apply to the next preview. Preview defaults holds:
  • Add preview variable: a Variable name, a New value, and Store as a secret for a value that should stay hidden. The portal shows no value once saved, but a value not stored as a secret is kept as written, and anyone in the organisation can read it with ankra application demo config get. A secret value is saved only as a reference and is mounted into the preview from a Kubernetes Secret.
  • Preview database: Enable preview database creates a temporary PostgreSQL database for each new preview, inside its namespace, with its own random password. It is removed with the preview.
  • Preview login: protects previews with a login. Ankra keeps the password, encrypted, so you can copy it from here with Copy password whenever you need it. A password set before Ankra kept preview passwords cannot be shown: rotate it once to get one you can copy. Rotating it leaves running previews on the old password until they next redeploy.
Nothing from the preview database is injected on its own, because every codebase names its configuration differently. Reference these placeholders in your preview variables’ values instead: What a preview starts with holds:
  • Built from: by default This app alone. Choose a profile attaches a stack profile (a Version, or blank for the latest), so every preview also starts that profile’s add-ons and manifests in the same namespace and removes them with it.
  • Shared services: Choose shared services lets every preview use one set of supporting services, such as a database or a cache. Stop sharing services detaches them without deleting them.
  • Database provisioning: a Migration command that runs through sh -c in the application image once a fresh preview database is ready, and Database extensions (comma separated, lowercase) such as vector.
The same defaults are in the CLI:

Resource limits

Each preview namespace carries its own hard ResourceQuota, so one preview cannot exhaust the staging cluster:

Options the portal form does not have

The New preview dialog asks only for the branch and the lifetime. For anything else, use the CLI:
An override may only name a component that --component selects: to tune one component of a full launch, list them all.

Reach the running preview

How a preview is reached depends on the organisation’s preview domain, set by someone whose role holds ai.manage under Ankra AI → AI workspaces → Domains for previews:
  1. A Preview domain, if configured, wins: previews get addresses under that wildcard zone, with its Ingress class and TLS secret.
  2. Otherwise the staging cluster’s own Ankra subdomain, when the cluster has DNS turned on.
  3. Otherwise inside the cluster only. The preview still runs. Use ankra application demo detail for its namespace and services.
The full order is under the preview URL. The card offers Open preview only for an HTTPS address. For any other address it reads No public address yet., and the address is in the preview_url field of ankra application demo list <application-id> -o json. While Ankra waits for DNS the card reads Address is awaiting DNS verification.

Update a branch preview’s image

A branch preview’s card has Update image. Pick the New image (the branch’s latest build or a published version) and a Lifetime (hours). Redeploying restarts the timer. Pull request previews have no Update image: a push to the pull request redeploys them.

Stop a preview

A preview stops itself when its lifetime ends: the namespace is deleted, with its database. To stop one early:
On the preview’s card, select Stop preview, then Stop this preview. The dialog reads Preview teardown accepted.
Preview namespaces are temporary. The preview database starts empty on every deploy and is removed with the namespace. Run your migrations on boot, or set a Migration command, and never point a preview at data you care about.

From the CLI and MCP

The deploy answer includes preview_url when Ankra resolved a public address.

No published image for the branch

When the registry holds nothing for the branch, the note in the New preview dialog says what Ankra found and Review preview stays disabled. Without more detail it reads “Build and publish this branch before launching a preview.” Unless Ankra has turned platform builders off for your organisation, ankra application demo deploy for a branch with no image queues a build of the branch’s head on them, and the answer says to retry once it lands. The portal has no button that fixes a missing build. Use the CLI: Ankra applies its own fixes first (publish readiness, a rerun of a failed run, a retry of a failed setup) and, when those cannot produce an image, dispatches an agent that investigates the repository and opens a pull request with the fix.
The answer names the agent run to follow.

What can go wrong