Skip to main content
Previews automatically create isolated deployment environments for pull requests and feature branches. When a PR is opened, Ryvn deploys the associated blueprint to a dedicated preview environment, allowing developers to test changes before merging. Previews are automatically destroyed when the PR is closed or after 7 days of inactivity. 
# frontend-previews.preview.yaml
# yaml-language-server: $schema=https://api.ryvn.app/v1/schemas/resources.json
kind: Preview
metadata:
  name: frontend-previews
spec:
  environment: preview-env
  blueprint: frontend-stack
  branches:
    - "feature/*"
    - "bugfix/*"
  inputs:
    - name: replicas
      value: 1

# preview-env.environment.yaml
# yaml-language-server: $schema=https://api.ryvn.app/v1/schemas/resources.json
kind: Environment
metadata:
  name: preview-env
spec:
  provider:
    type: aws
  installations: []

​
Properties

​
name

string — required Unique identifier for this preview configuration. Must be lowercase, alphanumeric with hyphens only. 
name: frontend-previews

​
environment

string — required Name of the environment where previews will be deployed. Should be a dedicated environment with auto-scaling to manage costs. 
environment: preview-env

​
blueprint

string — required Name of the blueprint to deploy for each preview. The blueprint’s services will be installed with preview-specific naming. 
blueprint: frontend-stack

​
branches

array — optional List of branch patterns that trigger preview creation. Uses filepath.Match syntax (not regex). If not specified, previews are created for all branches. Supported wildcards:
  • * matches any characters except /
  • ? matches single character
  • [abc] matches character class
  • [a-z] matches character range
branches:
  - "feature/*"
  - "bugfix/*"
  - "release/v*"

​
inputs

array — optional Blueprint input values for preview deployments. Override blueprint defaults for preview-specific configuration. 
inputs:
  - name: replicas
    value: 1
  - name: enable_debug
    value: true

​
inputs[].name

string — required Name of the blueprint input to set. 
name: replicas

​
inputs[].value

any — optional Value for the input parameter. Type should match the blueprint input definition. 
value: 1

​
staleDuration

string — optional Duration after which a preview with no new releases is considered stale and will be automatically closed. Uses Go duration format (e.g., “30m”, “72h”, “168h”). Minimum value is 15 minutes (“15m”). Defaults to “168h” (7 days) if not specified. 
staleDuration: "72h"  # 3 days

​
Stale Preview Exemption

You can prevent a preview from being automatically cleaned up due to inactivity by adding the preview:keep-alive label to the pull request. When this label is present, the preview will remain active until the PR is closed or merged, regardless of the configured staleDuration. This is useful for:
  • Long-running feature branches that need persistent preview environments
  • PRs that are under extended review
  • Demonstration or testing environments that need to remain available

​
Lifecycle

​
Creation

When a pull request is opened:
  1. Ryvn checks if the repository matches any preview’s candidate repositories
  2. Verifies the head branch matches the branch patterns
  3. Creates a unique release channel: preview-{org}-{repo}-pr{number}
  4. Deploys the blueprint to the preview environment
  5. Posts a GitHub comment on the PR with preview URLs

​
Destruction

Previews are automatically destroyed when:
  • The pull request is closed or merged
  • No new releases for the configured staleDuration (default: 7 days)
Stale cleanup can be prevented by adding the preview:keep-alive label to the PR. When destroyed, all service installations and the release channel are removed.

​
Preview URLs

Each preview installation receives a unique URL based on the installation name and environment’s public domain: 
https://{blueprint-name}-preview-{org}-{repo}-pr{number}.{public-domain}
Example: https://frontend-stack-preview-myorg-myapp-pr42.preview.example.com

​
Branch Patterns

Branch patterns use filepath.Match syntax (case-sensitive): 
branches:
  # Match feature branches
  - "feature/*"           # Matches: feature/login, feature/auth
                          # Does NOT match: feature/user/profile

  # Match release branches
  - "release/v*"          # Matches: release/v1.0.0, release/v2.1.3

  # Match with character class
  - "fix[0-9]"            # Matches: fix1, fix2, fix9
                          # Does NOT match: fixa, fix10

  # Match single character
  - "hotfix?"             # Matches: hotfix1, hotfixa
                          # Does NOT match: hotfix12

  # Match all (if empty or not specified)
  []                      # Matches: any branch
Important: * does not match /, so feature/* will not match feature/user/profile.

​
Examples

​
Basic Preview

Create previews for all branches: 
kind: Preview
metadata:
  name: app-previews
spec:
  environment: preview-env
  blueprint: full-stack
---
kind: Environment
metadata:
  name: preview-env
spec:
  provider:
    type: aws
    accountId: "123456789012"
  config:
    region: us-east-1

​
Filtered Branches

Only create previews for specific branch patterns: 
kind: Preview
metadata:
  name: frontend-previews
spec:
  environment: preview-env
  blueprint: frontend-stack
  branches:
    - "feature/*"
    - "bugfix/*"
    - "release/*"

​
Preview with Custom Inputs

Configure preview deployments differently from production: 
kind: Preview
metadata:
  name: api-previews
spec:
  environment: preview-env
  blueprint: api-service
  branches:
    - "feature/*"
  inputs:
    - name: replicas
      value: 1
    - name: cpu_cores
      value: 0.5
    - name: enable_debug
      value: true
    - name: log_level
      value: "debug"