Skip to main content
Previews enable automated deployments, triggered by pull requests and feature branches. They allow you to test changes in isolated environments before merging to your main branch. When you create a pull request, Ryvn automatically deploys your changes using blueprints, giving you a live preview of your application.
Previews help you catch issues early by providing isolated testing environments for every pull request.

​
How Previews Work

Previews are automatically triggered by GitHub webhooks when pull requests are opened, updated, or closed. Ryvn will create a unique blueprint installation for the preview and allow you to stand up a single or multiple services, depending on what your blueprint contains. Each preview is destroyed after the pull request is closed or merged or if there is no new activity for the configured stale duration (default: 7 days).
Add the preview:keep-alive label to a PR to prevent its preview from being automatically cleaned up due to inactivity. This is useful for long-running feature branches or extended reviews.
Previews may continue to incur additional infrastructure costs if you have a large number of PRs being opened and not being closed.

​
Enabling Previews

1

Configure Preview

Define previews in your resource YAML files with a blueprint and target environment. Make sure the target environment supports cluster auto-scaling.
2

Create Pull Request

Push your changes to a feature branch and create a pull request.
3

Automatic Deployment

Ryvn detects the PR and automatically deploys your changes using the preview configuration.
4

Test & Review

Access your preview environment to test changes and share with reviewers.
5

Cleanup

When the PR is closed or merged, the preview environment is automatically removed.

​
Using Previews

Previews are configured in your resource YAML files alongside your blueprints and environments. Here’s an example of a preview configuration: 
# yaml-language-server: $schema=https://api.ryvn.app/v1/schemas/resources.json
kind: Blueprint
metadata:
  name: frontend-blueprint
spec:
  description: "Frontend application"
  installations:
    - service: frontend
      config: |
        ingress:
          annotations:
            cert-manager.io/cluster-issuer: external-issuer
          className: external-nginx
          enabled: true
          hosts:
            - host: '{{.ryvn.installation.name}}.{{.ryvn.env.state.public_domain.name}}'
              paths:
                - path: /
                  pathType: Prefix
          tls:
            - hosts:
                - '{{.ryvn.installation.name}}.{{.ryvn.env.state.public_domain.name}}'
              secretName: '{{.ryvn.installation.name}}-tls'

    - service: backend
      config: |
        replicas: 3
---
kind: Preview
metadata:
  name: frontend-previews
spec:
  environment: previews
  blueprint: frontend-blueprint
See Preview Reference for detailed information about all the preview fields.

​
Preview Configuration

Each preview requires three main components:

​
Preview Properties

PropertyTypeRequiredDescription
namestringYesName of the preview. Must be lowercase alphanumeric with hyphens, max 63 characters.
environmentstringYesName of the environment where previews will be installed.
blueprintstringYesName of the blueprint to install.
staleDurationstringNoDuration before inactive previews are cleaned up (e.g., “72h”). Default: “168h” (7 days). Minimum: “15m”.

​
Environment Selection

The environment field specifies where your preview will be deployed. This should typically be a dedicated environment for previews that is using an auto-scaling cluster.
Avoid using production environments for previews to prevent accidental exposure of untested changes and resource contention.

​
Blueprint Configuration

The blueprint configuration is similar to environment installations but with preview-specific inputs: 
blueprint: "my-app-blueprint"
inputs:
  - name: "replica_count"
    value: 1
  - name: "debug_mode"
    value: true

​
Automating URL Generation

Each preview can get a unique URL assigned if your installation uses the correct ingress configuration that generates unique URLs. See the example below: 
ingress:
  annotations:
    cert-manager.io/cluster-issuer: external-issuer
  className: external-nginx
  enabled: true
  hosts:
    - host: "{{.ryvn.installation.name}}.{{.ryvn.env.state.public_domain.name}}"
      paths:
        - path: /
          pathType: Prefix
  tls:
    - hosts:
        - "{{.ryvn.installation.name}}.{{.ryvn.env.state.public_domain.name}}"
      secretName: "{{.ryvn.installation.name}}-tls"

​
Stale Preview Management

By default, previews are automatically cleaned up after 7 days of inactivity (no new releases). You can customize this behavior:

​
Custom Stale Duration

Set the staleDuration property to control how long a preview remains active without new releases: 
kind: Preview
metadata:
  name: api-previews
spec:
  environment: preview-env
  blueprint: api-service
  staleDuration: "72h"  # Clean up after 3 days of inactivity
The duration uses Go duration format: "30m" (30 minutes), "24h" (24 hours), "168h" (7 days). Minimum value is "15m".

​
Preventing Automatic Cleanup

Add the preview:keep-alive label to a pull request to exempt its preview from stale cleanup. The preview will remain active until the PR is closed or merged, regardless of inactivity. This is useful for:
  • Long-running feature branches
  • PRs under extended review
  • Demonstration environments

​
Troubleshooting

​
Common Issues

Problem: Pull request opened but no preview was created. Solutions: Verify that the service defined in the blueprint is using the Ryvn GitHub action. If your repository name was recently changed, this may also cause issues. Note: Previews are not supported for public helm-charts.
Problem: Preview is created but deployment fails. Solutions: Check the preview deployment logs in the Ryvn dashboard, verify all required inputs are provided, ensure the target environment has sufficient resources, and check for configuration errors in the blueprint.
Problem: New commits don’t trigger preview updates. Solutions: Verify GitHub webhook is properly configured, check that commits are pushed to the correct branch, ensure the preview system is running and healthy, and check for any rate limiting or webhook delivery issues.