Deployment Previews

Deployment Previews create temporary, fully isolated environments so you can test and share changes before merging them into production.

Here's a workflow diagram that explains the basic process

Developer
   │
   │ hx build --preview pr-200
   ▼
Build Artifact (tagged pr-200)
   │
   │ hx deploy --preview pr-200
   ▼
Preview Environment Created
   │
   ▼
https://pr-200-my-app.demo.com

What you get

• A shareable preview URL for testing and reviews
• Real cloud infrastructure generated from your deployment policy
• Runtime context variables injected into your app (app ID, environment, run ID, cloud, etc.)
• Automatic cleanup of preview resources when the preview is deleted

Core concepts

These concepts help explain how previews work inside Hyphen Deploy.

Deployment run

A deployment run executes a deployment policy for a specific build or revision of your application.

Project environments

Projects group apps, environments, and secrets. Environments (like development or production) isolate configuration and secrets for each stage of your application lifecycle.

Deployment policies

Deployment policies define what gets deployed, where it runs, and how it scales. You configure policies in the Hyphen app as part of setup.

Prerequisites

1. A cloud provider connected to your Hyphen organization
2. A project container registry configured
3. Your app initialized with the CLI (hx init) and the .hx file committed
4. At least one deployment policy created that has a hostname set.
   • At least one app in the deployment must have a hostname and DNS zone configured to create a preview deployment

Creating a Deployment Preview

Deployment previews use a two-step process:

1. Build your application and associate the build with a preview name.
2. Deploy that build to create the preview environment.

This allows you to reuse the same build across multiple preview deployments.

Option 1: Use the CLI

Hyphen Deployment Previews let you create isolated environments for branches, pull requests, or temporary testing.

Using the CLI, you can:

• Build an artifact associated with a preview
• Deploy that build to a preview environment
• Reuse an existing build for future preview deployments

Step 1: Install the CLI

sh -c "$(curl -fsSL https://cdn.hyphen.ai/install/install.sh)"

powershell -c "irm https://cdn.hyphen.ai/install/install.ps1 | iex"

Step 2: Build with a Preview Label

Navigate to your app's directory and use the --preview flag when building to associate the build with a preview name.

hx build --preview <preview-name>

Example

hx build --preview pr-200

This command:

• Builds your application
• Uploads the artifact to your artifact registry
• Tags the build with the preview name

For more information on the Build command, see the Build Guide.

📘

**Important **

This step does not create the preview environment yet.

The preview name is stored with the build so it can be used later during deployment.

Step 3: Create and deploy a Deployment Preview

1. To create a preview deployment you must provide:

   • a preview name (used to match the build) • a hostname prefix (used to generate the preview URL)

The prefix gets pre-pended to the deployments existing hostname.

hx deploy <deployment-policy-name> --preview <preview-name> --prefix <prefix>

Example

hx deploy location-app-gcp --preview pr-200 --prefix pr-200

Example preview url would be: https://pr-200-my-app.demo.com

Hyphen will:

• Create the preview
• Look for builds associated with that preview
• Start a deployment run

Step 4: Reuse an Existing Build

If a build already exists for the preview, you can skip building again using --no-build.

hx deploy deploy-to-dev --preview "pr-200" --no-build

Option 2: In the Hyphen App

You can also create preview deployments directly from the Hyphen App.

However, preview builds must still be created using the CLI. Once a build exists for a preview, you can trigger deployments from the UI.

To create deployment previews in the Hyphen app:

1. Navigate to Deploy → then choose the policy you want to create a preview for.

2. Open the environment dropdown (for example Production) and select New Preview…

   

3. To create a preview deployment you must provide:

   • a preview name (used to match the build) • a hostname prefix (used to generate the preview URL)

   Then select Create

1. You may see a warning indicating that your apps must be built before the preview can be deployed.

   

2. Using the CLI, create a build for your new deployment preview using the same name.

   Use the --preview flag when building to associate the build with a preview name.

   Bash

   hx build --preview <preview-name>

   Example

   hx build --preview pr-200

   You can also use the CLI to build and run you're new deployment

   hx deploy <deployment-policy-name> --preview <preview-name> --prefix <prefix>

3. You're new deployment preview is now ready to be deployed in the Hyphen App. Click Deploy Preview to run the deployment using the latest build associated with that preview.