Set up preview blueprints

1. Navigate to Environments in your project

2. Click Create preview blueprint

3. Configure the blueprint:

   • Name: Enter a name (e.g., pr-previews)
   • Naming convention: Select how preview resources should be named
   • Prefix / Suffix: Toggle whether to prepend or append pull request numbers or branch names to resource names

4. Click Add trigger:

   • Kind: Select Git pull request or Git push
   • Repository: Select the repository to watch

5. Click Continue to open the visual editor

The visual editor opens where you can define the resources that will be created in each preview environment.

Use the visual editor to define what gets created in each preview environment. Connect nodes together to build your preview infrastructure.

1. Start with a Build on trigger node that builds code from the pull request or branch

2. Add deployment nodes to deploy the built code to services

3. Add infrastructure nodes to create databases, volumes, or other resources

4. Configure networking to expose services with unique URLs

5. Click Save preview blueprint

Common patterns

Simple frontend or API

Build your code and deploy it as a single service with a public URL. Each preview gets its own URL so reviewers can open the exact version from the PR.

Nodes: Build on trigger → Create service → Expose port with generated domain

Full stack application

Build your application, provision a fresh database for the preview, deploy the application, and inject the database credentials. Each preview environment is fully isolated with its own data.

Nodes: Build on trigger → Create addon (e.g. PostgreSQL) → Deploy build → Link addon credentials to service

This is the most common pattern for web applications. Because the database is created fresh for each preview, you can seed it with test data using a job node that runs after the database is ready.

Full stack with seed data

Extend the full stack pattern by running a one-off job after the database is ready to load fixtures or seed data. Alternatively, fork your database from a snapshot to restore pre-seeded data more efficiently. The preview is then ready to use immediately after deployment without manual setup.

Nodes: Build on trigger → Create addon (or fork from snapshot) → Run job (seed data, optional) → Deploy build → Link addon credentials

Microservices

Build and deploy multiple services in the same preview. Internal services communicate using Northflank's private networking, while only the public-facing service is exposed externally.

Nodes: Build service A → Build service B → Deploy service A → Deploy service B → Expose service A

Use condition nodes to skip certain services if the PR only touches specific parts of the codebase.

Branch-specific overrides

Use the Skip node execution option with conditional functions like fn.if() in node references to change what gets deployed based on which branch or repository triggered the preview. For example, skip creating a full database and deploy a lightweight mock instead when the PR is against a docs branch.

Nodes: Build on trigger → Condition (check ${triggers.repo.branch}) → Deploy full stack (true path) → Deploy lightweight mock (false path)

Preview blueprints can create or update environments from Git events, webhook requests, or a schedule. Add a trigger in the blueprint editor. Select its Kind. Configure the trigger. Save the trigger and blueprint.

Workflows and preview blueprints share trigger types and filtering controls.

GitHub check-suite triggers do not wait for every check suite on the commit. GitHub tagged-release triggers require a release event, rather than a tag push alone.

Scheduled previews

Each blueprint accepts one cron trigger, with a minimum interval of 10 minutes. A scheduled run does not delete and recreate an existing environment automatically. Environment naming determines whether the run creates a new environment or updates an existing one.

With the default random names, scheduled runs can create separate environments. Configure automatic cleanup for previews that you no longer need.

Webhook previews

To start a preview with a webhook:

1. Select Webhook as the trigger kind.
2. Copy the Webhook URL.
3. Save the trigger.
4. Save the blueprint.
5. Send a GET or POST request to the URL to start a preview run.

Pass arguments in the URL query string. To create or update a named preview, supply name, for example ?name=review-demo. Requests with the same name target the same active preview within that blueprint.

See webhook parameters for arguments and Git references. Use the preview URL copied from the blueprint, rather than a workflow URL.

Pause triggers

To pause a trigger, turn off Enable trigger in its form. See pause preview triggers for the effects on existing previews.

Click Settings in the blueprint editor to configure preview environment behavior:

Resource naming

Controls how resources created inside each preview environment are named.

Use pull request ID: Resources are named with the pull request number (e.g., api-pr-123). This is predictable and stable; the name stays the same if you push new commits to the same PR.

Use branch name: Resources are named with the branch name (e.g., api-feature-login). Useful when you want the resource name to reflect what is being reviewed, but names can become long for branches with verbose naming conventions.

Custom naming: Use template variables to define your own naming scheme, e.g. api-${triggers.repo.pullRequestId}-${triggers.repo.sha}. By default, Northflank automatically adds ${args.name} as a prefix or suffix to ensure uniqueness, but you can remove this if needed.

Resource limits

Set smaller resource plans for previews than production to manage costs. For example, you might run a 0.1 vCPU / 256 MB container for a preview API instead of the 1 vCPU / 1024 MB plan used in production.

Preview expiry

Enable Allow preview environments to expire to delete previews automatically after a configured lifetime. Set the lifetime with Hours and Minutes.

Enable Reset duration on update to environment to restart the timer when the preview runs again. Without this control, later runs retain the existing expiry time.

Use branch contents

Enable Enable using branch contents to use the blueprint file from the branch associated with a preview. This requires GitOps and the configured file path in that branch of the GitOps repository.

If the preview branch differs from the configured GitOps branch, Northflank fetches the file from the preview branch. The run uses that file's root specification. The saved blueprint still controls triggers and argument overrides. If Northflank cannot read or accept the file, the run request fails.

Teardown

Add a teardown specification for cleanup when a preview environment is deleted. Use it for external resources or cleanup jobs that normal preview deletion does not handle. Preview deletion runs the teardown unless you choose to skip it. See run teardown workflows for execution and failure policies.

Before relying on automatic triggers, test your preview blueprint manually:

1. Click Run in the blueprint editor

2. Select a commit from the repository

3. Click Create

This creates a preview environment without opening a pull request, allowing you to verify the blueprint works correctly.