Preview environments

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

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

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.

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.

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.

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.

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.

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.

name: albumshots

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

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.

Dashboard workflow

A preview environment is a complete, throwaway copy of a stack, deployed from a pull request branch, reachable at its own URL, and torn down when the pull request closes. Stackdome calls the feature Previews, in the sidebar under Platform.You do not point Previews at an existing stack. You point it at a repository, and the stack comes from a stackfile committed in that repository. Every pull request against that repository’s base branch then gets its own stack, built from the stackfile at that pull request’s head commit.

Dashboard prerequisites

A connected git provider. Previews are driven by GitHub webhook deliveries, so the repository must be reachable through a GitHub App installation you connected under Git Providers. See Deploy from git. The repository picker also accepts a plain public URL, but a public URL only supports environments you create by hand — pull request automation needs a connected provider.
A stackfile in the repository. This is the template for the environment: it defines the whole stack — every resource, its source, its ports, its environment. See Write the stackfile below.
A cluster with room to run it. Each open pull request runs a full copy of the stack. Read Capacity before you enable a busy repository.

Write the stackfile

The stackfile is the one thing you have to author yourself. Commit it at the path you give the configuration — by default stackfile.yaml at the repository root — and keep it on the branches you want previewed, because Stackdome reads it at the pull request’s head commit, not from your base branch.The smallest stackfile that works names the stack, declares one resource, gives that resource a source, and exposes one port:

name: albumshots

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

That is enough to get an environment. The rules those five keys follow:

name and at least one entry under resources are required.
Each resource needs exactly one source — build, to build from git, or image, to run a prebuilt one. Never both.
A build needs repo. branch and tag are mutually exclusive; commit is an optional pin and requires one of them. Setting no revision fields uses the repository’s default branch.
Each port needs a name and a valid port number. public: true is what earns it a URL; a port without it stays internal to the stack.

One thing to expect: on a preview, Stackdome rewrites the branch of any resource whose build.repo matches the configuration’s repository, pinning it to the pull request’s head commit. So branch: main above does not mean previews build main — it is only what that resource does outside a preview.

This is a minimal example, not a reference. See the Stackfile reference for the fields accepted by the installed release and validate every change with stackdome validate.

Enable a repository

Previews lists the repositories you have configured, each with its base branch and how many environments are currently live.

The Configured repositories panel on the Stackdome Previews page, listing two entries — stackdome for the repository Stackdome/stackdome, and test-private-repo with its repository path redacted

Open the wizard

Click Enable repository.

Pick the repository

The first step is a repository picker with two tabs, Connected provider and Public URL. Choose the repository from your connected provider, then click Continue.

Fill in the configuration

Field	Required	Notes
Name	Yes	Prefilled from the repository name. Cannot be changed later.
Base branch	Yes	The branch pull requests target. Only pull requests against this branch get an environment.
Stackfile path	No	Defaults to `stackfile.yaml`. Fetched from the repository on every deploy — a wrong path shows up as a Failed environment.
Max active previews	No	Defaults to `10`; must be between 1 and 50.
Environment variables	No	Applied to every environment this configuration creates. Reference a saved secret rather than pasting a raw value.

The Enable repository dialog in Stackdome, on its configuration step for Stackdome/test-repo, with a Name field reading test-repo and the hint Cannot be changed later, a Base branch dropdown set to main, a Stackfile path field reading stackfile.yaml, the label Max active previews at the fold with the rest of the form scrolled out of view, and Back and Enable previews buttons

Save

Click Enable previews. The repository now appears in the Previews list, and the next pull request event on it will create an environment.

Everything except the name stays editable afterwards, from Settings on the configuration’s page.

Environment variables

Two layers of environment variables land on top of what the stackfile itself declares, in this order:

.env.preview — an optional dotenv file at the repository root, read at the pull request’s head commit. A missing or unreadable file is simply skipped.
The configuration’s Environment variables — the ones you entered in the wizard. These win over .env.preview.

Both layers apply to every resource in the stackfile. For how values and secret references work, see Environment variables.

What happens on a pull request

Stackdome processes exactly two GitHub event types: installation and pull_request. push deliveries are accepted and dropped. Within pull_request, these are the actions that do something:

Action	What Stackdome does
`opened`	Creates an environment for the pull request. If one somehow already exists, syncs it to the head commit instead.
`reopened`	Same as `opened`.
`synchronize` (a new commit pushed to the pull request)	Syncs the existing environment to the new head commit. If no environment exists yet, creates one.
`closed` (merged or not)	Starts tearing the environment down.

Any other pull_request action — labelled, assigned, edited, review requested — is ignored.A delivery is also dropped, deliberately and without error, when:

The head branch lives in a fork. Fork pull requests carry untrusted code and are never built.
The pull request’s base branch is not the configuration’s base branch.
No preview configuration matches the repository.
The action is closed but there is no environment to remove.

Every delivery is logged with its outcome, including the drops, so a preview that never appears is diagnosable from the API server log.

Where the preview URL appears

In the dashboard

Open the configuration from Previews. Each environment is a card showing the pull request number, the branch, the short commit, a status word — Ready, Pending, or Failed — and, once it is live, a chip per publicly exposed resource that links straight to its URL. A resource with no publicly exposed port gets no chip, so a card can be Ready with nothing to click. Search filters by pull request number, branch, or commit; the Status and Sort controls narrow and reorder the grid.

The detail page for the stackdome preview configuration, headed with the repository URL, a search field for PR number, branch or commit, and four environment cards for pull requests 186, 185, 183 and 182 — all marked READY, with 186, 183 and 182 showing their branch and short commit, and 185 showing a clickable api-server resource chip

Each publicly exposed port gets a pr-<number>- prefix on its subdomain, so pull request 185’s URL is distinct from pull request 186’s and from your production stack’s. See Domains and TLS for how the rest of the hostname is put together.

In the pull request

Stackdome also posts the environment’s state back to the pull request as a single sticky comment, created the first time the environment reports in and edited in place after that. It carries:

A heading for the current state — live, deploy failed, or deleted.
The failure message, when the deploy failed.
The deployed commit.
A table of resources and their URLs.

If someone deletes the comment, the next update recreates it. Nothing to switch on: this happens whenever the repository is a GitHub repository with an App installation Stackdome can mint a token for. For a repository added by public URL, or one whose App installation is gone, the comment is skipped and the dashboard remains the place to look.

Lifecycle and cleanup

An environment moves through Provisioning → Deploying → Ready, or lands in Failed. A teardown puts it in Deleting.Three things end an environment:

The pull request closes — merged or not. The closed event starts the teardown.
You delete it — the ··· menu on the card, then Delete.
You delete the whole configuration — but only after its environments are gone. Stackdome refuses otherwise and tells you to delete the environments first.

Teardown deletes the environment’s stack and everything under it, waits for the deployment destination to finish removing it, then removes the environment record and marks the sticky comment as deleted. Nothing expires on a timer, so an environment attached to a long-lived pull request keeps running — and keeps consuming destination capacity — until that pull request closes.

Creating one by hand

You can also create an environment without a pull request event, which is the way to test a configuration before wiring anything up. On the configuration’s page, click New preview environment:

Field	Required	Notes
PR number	Yes	Used for the name and the `pr-<number>-` subdomain prefix.
Branch	Yes	Deploys this branch’s latest commit.
Stackfile content	No	Under Advanced. Paste a stackfile to use instead of the one in the repository.
Image overrides	No	Under Advanced. One `resource=image` per line, to pin a resource to a prebuilt image instead of building it.

Then click Create environment. A manual environment does not follow new commits on its own — use Sync from the card’s ··· menu to move it to the branch’s latest commit.

Capacity

Every open pull request builds and runs a full copy of the stack — every resource, and every volume with its mount, that the stackfile declares. Ten open pull requests against a repository with a five-resource stack means fifty running resources on top of production.There is no build-concurrency limit in Stackdome. Nothing queues or throttles simultaneous builds: if ten pull requests are opened at once, ten sets of builds start at once and compete for the same destination capacity. On single-node self-hosted Kubernetes compute, that is enough to saturate the node and push builds into deploy timeouts.The only limit is Max active previews, per configuration, defaulting to 10. It caps how many environments can exist at once — not how many build at once. When a configuration is at its cap, a new pull request creates nothing: the delivery is logged as skipped and no comment is posted, so the pull request looks like previews are simply not enabled. Set the cap to what your deployment destination can actually hold.

Deploy from git

Connect a repository and verify its ordinary deployment workflow.

Stackfile reference

Check the fields and current validator behavior used by previews.

Get started

Build and ship

Debug and operate

Dashboard walkthroughs

Preview environments

Outcome

Prerequisites

Agent prompt

Agent actions

Success criteria

CLI and Stackfile boundary

Dashboard workflow

Dashboard prerequisites

Write the stackfile

Enable a repository

Environment variables

What happens on a pull request

Where the preview URL appears

In the dashboard

In the pull request

Lifecycle and cleanup

Creating one by hand

Capacity

Deploy from git

Stackfile reference

​Outcome

​Prerequisites

​Agent prompt

​Agent actions

​Success criteria

​CLI and Stackfile boundary

​Dashboard workflow

​Dashboard prerequisites

​Write the stackfile

​Enable a repository

​Environment variables

​What happens on a pull request

​Where the preview URL appears

​In the dashboard

​In the pull request

​Lifecycle and cleanup

​Creating one by hand

​Capacity

​Related tasks

Deploy from git

Stackfile reference

Outcome

Prerequisites

Agent prompt

Agent actions

Success criteria

CLI and Stackfile boundary

Dashboard workflow

Dashboard prerequisites

Write the stackfile

Enable a repository

Environment variables

What happens on a pull request

Where the preview URL appears

In the dashboard

In the pull request

Lifecycle and cleanup

Creating one by hand

Capacity

Related tasks