Skip to main content

Documentation Index

Fetch the complete documentation index at: https://ryvn.ai/docs/llms.txt

Use this file to discover all available pages before exploring further.

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

Some nginx-specific annotations are being deprecated. See Ingress NGINX Retirement.
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"

​
Blueprint preview releases

In addition to deploying service installations, previews automatically publish blueprint preview releases when a PR modifies existing blueprint YAML files. This lets you test blueprint changes — new inputs, updated service configurations, added installations — without merging to your main branch. When a PR is opened or updated, Ryvn diffs the PR against the base branch and syncs only the modified blueprint files. For each changed blueprint that already exists on your main branch, a preview release is created on the PR’s release channel. Each preview release follows the version format {N}.0.0-preview.{prNum}.{timestamp}.sha-{commit}, which is idempotent per blueprint definition within the same PR.
Only blueprints that already exist on your main branch and were modified in the PR receive preview releases. Unchanged blueprints are not touched, and brand-new blueprints introduced in a PR are skipped — they need to be merged first so the canonical blueprint record exists before preview releases can be created against it.

​
How blueprint preview releases are used

Blueprint preview releases are attached to the PR’s preview channel and are available for blueprint installations pinned to that channel. When the PR is closed or merged, the preview channel is torn down and all associated preview releases are pruned automatically. Preview releases cannot be promoted to non-preview release channels. This prevents unreviewed blueprint changes from accidentally reaching production environments.

​
Viewing preview releases

The Releases tab on a blueprint page includes filters for managing preview visibility:
  • Hide previews (enabled by default) — filters out preview releases so the list shows only stable releases.
  • Release channel filter — narrows the list to releases on specific channels, including preview channels.
Preview releases display a Preview badge in the releases table.

​
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.