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.deploypermission. 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.
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:sha-<7>: the first seven characters of the branch’s head commit, the only tag that is provably this head’s build.- For each open pull request from the branch,
sha-<7>of its merge commit, thenpr-<number>. - The branch name, with every character other than letters, digits,
.,_and-replaced by-(feature/loginbecomesfeature-login).
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:
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§ion=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.
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 -cin the application image once a fresh preview database is ready, and Database extensions (comma separated, lowercase) such asvector.
Resource limits
Each preview namespace carries its own hardResourceQuota, 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:--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 holdsai.manage under Ankra AI → AI workspaces → Domains for previews:
- A Preview domain, if configured, wins: previews get addresses under that wildcard zone, with its Ingress class and TLS secret.
- Otherwise the staging cluster’s own Ankra subdomain, when the cluster has DNS turned on.
- Otherwise inside the cluster only. The preview still runs. Use
ankra application demo detailfor its namespace and services.
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:- Portal
- CLI
- MCP
On the preview’s card, select Stop preview, then Stop this preview. The dialog reads Preview teardown accepted.
From the CLI and MCP
- CLI
- MCP
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.
What can go wrong
Related
- Preview demos: the concept, the namespace model and the isolation
- PR preview environments: the automatic preview for every pull request
- Ship your app: from a repository to a running application, and which builder publishes which tags