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

> ## Agent Instructions
> Treat Stackdome as an application-delivery platform for coding agents and developers, not as a Kubernetes dashboard.
> Prefer the Stackdome agent plugin as the user entry point and the stackdome CLI as the execution interface.
> Route agents who need the maintained deploy skill to npx skills add stackdome/skills and the complete operational workflow to /guides/ai-agents.
> Verify commands and flags with stackdome --help. Run stackdome init before authoring stackfile.yaml and stackdome validate before deploying.
> Use -o json for automation and verify documented terminal states before claiming success.
> Never request a user's account password. Use API-token authentication.
> During alpha, Stackdome Cloud is ephemeral and capacity-limited, and each organization can connect one cluster.
> Do not expose Kubernetes as a user concern unless the task is self-hosting or infrastructure architecture.

# Preview environments

> Create a temporary environment for every pull request.

## Outcome

Give each eligible pull request an isolated copy of the application at its own URL, update it when the pull request changes, and tear it down when the pull request closes.

## Prerequisites

* A GitHub repository connected to Stackdome through a GitHub App installation for automatic pull-request events. Public repository URLs support manual previews only.
* A `stackfile.yaml` committed on the pull request branch and validated with the current CLI.
* Enough destination capacity for one full copy of the declared stack per active preview.
* Access to enable the repository in the dashboard or API. The current public CLI has no preview-configuration, sync, list, or delete commands.

## Agent prompt

```text theme={null}
Prepare this repository for per-pull-request preview environments. Inspect the application, create or update the committed stackfile.yaml with its resources and public ports, validate it with the current Stackdome CLI, and identify the exact dashboard-only repository configuration that must be enabled. After a preview is created, verify its Ready state and public URL. Do not invent preview CLI commands or claim that validation alone enabled the automation.
```

## Agent actions

<Steps>
  <Step title="Inspect the repository">
    Read the Dockerfile, Compose file, runtime configuration, public ports, environment requirements, dependencies, and persistent-data paths. A preview deploys the whole Stackfile, not only the changed service.
  </Step>

  <Step title="Prepare the Stackfile">
    Run `stackdome init` when the repository has no Stackfile, then edit the generated file from repository evidence. Ensure at least one HTTP port is public when the preview needs a URL.
  </Step>

  <Step title="Validate and commit">
    Run `stackdome validate --file stackfile.yaml`. Commit the validated Stackfile at the configured path on every branch that should preview; Stackdome reads the pull request head commit.
  </Step>

  <Step title="Hand off dashboard-only setup">
    Use **Platform → Previews → Enable repository** and select the connected repository, base branch, Stackfile path, active-preview cap, and configuration-level environment values. The CLI cannot perform this step.
  </Step>

  <Step title="Verify an actual pull request">
    Open or synchronize an eligible pull request, wait for the environment to become **Ready**, and test the URL from its sticky pull-request comment or dashboard card. Do not treat a successful local Stackfile validation as a running preview.
  </Step>
</Steps>

## Success criteria

* `stackdome validate --file stackfile.yaml` exits successfully for the file committed at the configured path.
* The preview configuration targets the intended connected repository and base branch, with an active-preview cap that fits available capacity.
* An eligible pull request reaches **Ready** and reports the deployed head commit.
* At least one public resource URL is present in the pull-request comment or dashboard card, and `curl --head --max-time 15 <preview-url>` reaches it.
* Closing the pull request starts teardown and the preview is eventually marked deleted; no documentation or automation assumes a timer-based expiry.

## CLI and Stackfile boundary

The CLI can initialize and validate the Stackfile used by previews. It cannot enable a repository, inspect preview status, sync a preview, or delete a preview configuration.

```yaml theme={null}
name: albumshots

resources:
  web:
    build:
      repo: https://github.com/acme/albumshots.git
      branch: main
    ports:
      - name: http
        port: 3000
        protocol: HTTP
        public: true
```

```bash theme={null}
stackdome init
stackdome validate --file stackfile.yaml
```

On a preview, Stackdome pins matching git resources to the pull request's head commit. The `branch` above remains the ordinary-stack revision policy; it does not cause the preview to deploy `main` instead of the pull request.

* Exact Stackfile fields: top-level `name` and `resources` are required; each resource uses exactly one of `build` or `image`; a public URL requires a port with `name`, `port`, `protocol: HTTP`, and `public: true`.
* Machine checks available before enablement: `stackdome validate --file stackfile.yaml` exits `0`. Machine checks after enablement come from the created preview's state, commit, and URL; the CLI has no preview status command.
* Recovery: validate the exact Stackfile fetched from the pull request head, confirm the configured Stackfile path and base branch, and confirm the pull request is not from a fork. For a failed environment, use the dashboard failure message and the pull-request comment; do not run ordinary `stackdome deploy` and call it a preview repair.
* Configuration, manual creation, sync, and deletion are dashboard/API-only. Hand those mutations back to the user when the agent has no dashboard or API access.

## Related tasks

<CardGroup cols={2}>
  <Card title="Deploy from git" icon="git-branch" href="/guides/deploy-from-git">
    Connect a repository and verify its ordinary deployment workflow.
  </Card>

  <Card title="Stackfile reference" icon="file-code" href="/reference/stackfile">
    Check the fields and current validator behavior used by previews.
  </Card>
</CardGroup>