> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ankra.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# PR Preview Environments

> Every pull request on a connected application gets a live, throwaway preview on your staging cluster - with one status comment that updates in place

<Note>
  Open a pull request on a [connected application](/concepts/applications) and Ankra deploys that PR's build to your organisation's staging cluster, then posts a status comment with a public preview link. Push again and it redeploys. Close or merge and it is torn down. No pipeline YAML, no ingress wiring, no cleanup.
</Note>

***

## What you get

Minutes after opening a PR, a comment like this appears and keeps itself up to date:

> ### 🚀 Ankra Preview
>
> | Application | Status  | Preview             | Commit    | Updated (UTC)         |
> | :---------- | :------ | :------------------ | :-------- | :-------------------- |
> | **website** | ✅ Ready | **Visit Preview ↗** | `524ba32` | Aug 8, 2026, 10:26 PM |
>
> <sub>⏳ Expires Aug 9, 22:26 UTC · 🔁 Redeploys on every push</sub>

The preview runs in its own isolated namespace on the staging cluster, PodSecurity-hardened and quota-bounded, exactly like a manually launched [preview demo](/concepts/applications#preview-demos). When the Ankra GitHub App has the optional Deployments permission, the PR also gets a GitHub deployment entry, so the preview shows up in the PR's environments box.

***

## Prerequisites

<Steps>
  <Step title="Connect the repository as an application">
    The repository must be a [connected application](/concepts/applications) (GitHub only for now). Application setup opens a PR that adds the canonical build-and-publish workflow - this is what builds your PR's container image and pushes it with a `pr-<number>` tag. Automatic previews key on that tag.
  </Step>

  <Step title="Configure a staging cluster">
    An admin sets the organisation's staging cluster under **AI** → **Settings** → **Workspaces**. Without it, pull requests deploy nothing - this is the switch that turns the feature on.
  </Step>

  <Step title="Optional: bring a demo base domain for HTTPS">
    By default previews are served under the staging cluster's own Ankra DNS zone (`*.ankra.cc`, or the [Ankra domain your organisation selected](/concepts/applications#the-preview-url)) over plain HTTP. For HTTPS (or your own hostnames), configure a **demo base domain** with an ingress class and TLS secret in the same settings screen.
  </Step>
</Steps>

***

## The status comment

One marker-tagged comment per PR, updated in place - never a stream of new comments.

| Status                   | Meaning                                                                                                                               |
| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------- |
| 🔄 **Building**          | The PR image has not landed in the registry yet. Ankra polls for it for a few minutes and updates the comment when it arrives.        |
| ✅ **Ready**              | Deployed. The **Visit Preview** link opens the running PR build; the **Commit** column shows the deployed head SHA.                   |
| ⚠️ **Build unavailable** | No `pr-<number>` image was published for this head. Fork PRs and repositories on an old workflow template cannot push preview images. |
| ❌ **Failed**             | The deploy itself failed. The reason appears in a caution callout under the table.                                                    |
| ⚪ **Stopped**            | The PR was closed or merged and the preview namespace was deleted.                                                                    |

Lifecycle:

* **On open**: the preview deploys as soon as the PR's image build publishes.
* **On every push**: the preview redeploys with the new head; the comment's Commit and Updated cells refresh.
* **On close or merge**: the namespace is torn down immediately and the comment flips to ⚪ Stopped.
* **On expiry**: previews are time-limited (24 hours by default) and reaped automatically; pushing again deploys a fresh one.

***

## Configuration and data

Automatic previews inherit the application's **demo environment defaults** - env vars, secret slots, and the optional throwaway Postgres - configured behind the gear on the application's **Demos** tab. See [environment variables and a throwaway database](/concepts/applications#environment-variables-and-a-throwaway-database). If your app needs configuration to boot, set the defaults once and every PR preview gets them.

***

## Troubleshooting

| Symptom                            | What to check                                                                                                                                                                                                                                                                   |
| ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| No comment appears on a new PR     | Is the repository a connected application, and is the staging cluster set? If both hold, push a new commit (or close and reopen the PR) - either re-triggers the preview.                                                                                                       |
| Stuck on 🔄 Building               | Open the PR's **Build and Publish** workflow run. The `pr-<number>` image tag must reach the registry; a failed or skipped build leaves the preview waiting until the next push.                                                                                                |
| ⚠️ Build unavailable               | Fork PRs cannot push preview images by design. For same-repo PRs, the repository is likely on an old workflow template - re-run application setup to update the workflow.                                                                                                       |
| ✅ Ready but the URL errors or 503s | The preview runs *your PR's container* - a crash on boot is application-side, not platform-side. Inspect the preview namespace's pod logs on the staging cluster (portal Demos tab or `kubectl`). A config file change that breaks the container's server is the classic cause. |
| The preview URL does not resolve   | The staging cluster's DNS zone must be active (or a demo base domain configured). If it resolves publicly but not on your machine, a stale negative DNS cache is usually to blame - retry against another resolver.                                                             |
| HTTP instead of HTTPS              | Platform-zone previews (`*.ankra.cc`, or your selected Ankra domain) are HTTP by design. Configure a demo base domain with a TLS secret for HTTPS.                                                                                                                              |

***

## Related

* [Branch demos](/guides/branch-demos) - the manual launch dialog, its environment variables, throwaway database, and teardown timer
* [Preview demos](/concepts/applications#preview-demos) - launch a demo manually from the portal, CLI, or the `deploy_pr_demo` MCP tool
* [The preview URL](/concepts/applications#the-preview-url) - how the public hostname is resolved
* [GitHub Actions CI/CD pipeline](/guides/cicd-pipeline) - the delivery flow the preview build rides on