Preview Environments

Preview environments are a kubriX Prime delivery feature that creates temporary Argo CD applications for pull requests. They help teams validate application changes before they are promoted through the regular Kargo stages.

When preview environments are enabled, kubriX uses an Argo CD ApplicationSet pull request generator to scan pull requests in the application repository. Pull requests that match the configured labels are deployed from their current head_sha into isolated preview namespaces.

How it works

The preview environment feature is configured in two layers:

• previewEnvironmentsDefaults on the team configuration defines the default behavior for all matching applications of a team.
• previewEnvironments in an application's app-stages.yaml can override the team defaults for a specific application.

For every matching pull request, kubriX creates a preview application and namespace:

Resource	Naming pattern
Argo CD application	<appName>-preview-pr-<number>
Namespace	<teamName>-<appName>-pr-<number>

The application chart receives the pull request number as a Helm value:

kubriXPreviewPRNumber: "<pull-request-number>"

In hub-and-spoke setups, kubriX also injects the ingress domain of the target spoke cluster:

kubriXIngressDomain: "<spoke-ingress-domain>"

Prerequisites

• kubriX Prime is used.
• The application is onboarded through the multi-stage app with Kargo pipeline via the official team-onboarding chart.
• The application repository follows the expected naming convention: <teamName>-<appName>.
• The application repository contains the kubriX-specific app-stages.yaml.
• The repository is visible to the team's multi-stage ApplicationSet.
• The GitHub token secret exists as <teamName>-appset-github-token.
• The pull request has one of the configured labels, for example preview.
• Every file listed in previewEnvironments.valuesFiles exists in the application repository.

If the preview environment should expose an ingress, the application chart must support preview-specific host names. A common pattern is to use tpl in the chart template so values can reference kubriXPreviewPRNumber.

Team defaults

Platform teams can enable preview environments for a team in platform-apps/charts/team-onboarding/values-customer.yaml.

In the default workflow, application teams create the team onboarding pull request and platform teams review and merge it.

teams:
  - name: team1
    multiStageKargoAppSet:
      github:
        organization: my-org
    previewEnvironmentsDefaults:
      enabled: true
      labels:
        - preview
      requeueAfterSeconds: 1800
      valuesFiles:
        - values.yaml
        - values-preview.yaml

Hub-and-spoke

In hub-and-spoke setups, set destinationCluster to the spoke stage where preview environments should run.

teams:
  - name: team1
    multiStageKargoAppSetSpoke:
      github:
        organization: my-org
    previewEnvironmentsDefaults:
      enabled: true
      destinationCluster: nonprod
      labels:
        - preview
      requeueAfterSeconds: 1800
      valuesFiles:
        - values.yaml
        - values-preview.yaml

The destination cluster is selected through Argo CD cluster secret labels. The selected cluster secret must match:

spoke.kubrix.io/stage: nonprod

App-specific overrides

Application teams can override the team defaults in their app-stages.yaml.

previewEnvironments:
  enabled: true
  labels:
    - qa
  requeueAfterSeconds: 600
  valuesFiles:
    - values.yaml
    - values-qa.yaml

App-specific values are merged over the team defaults. This allows the platform team to define a default policy while individual apps choose their own label or preview values files.

Preview ingress

Use kubriXPreviewPRNumber to create a unique host name per pull request.

ingress:
  hosts:
    - host: team1-my-app-pr-{{ .Values.kubriXPreviewPRNumber }}.apps.example.com

In hub-and-spoke setups, use kubriXIngressDomain to target the selected spoke cluster domain.

ingress:
  hosts:
    - host: team1-my-app-pr-{{ .Values.kubriXPreviewPRNumber }}.{{ .Values.kubriXIngressDomain }}

The chart template must render host values with tpl:

rules:
  {{- range .Values.ingress.hosts }}
  - host: {{ tpl .host $ | quote }}
  {{- end }}

Lifecycle

1. A developer opens or updates a pull request.
2. The configured label, for example preview, is added to the pull request.
3. The ApplicationSet controller detects the pull request.
4. Argo CD creates a preview application from the pull request head_sha.
5. The application is deployed into the preview namespace.
6. When the pull request is updated, the preview application follows the new head_sha.
7. When the label is removed or the pull request is closed, the preview application and namespace are pruned.

requeueAfterSeconds controls how often the ApplicationSet controller checks for pull request changes. If it is not configured, kubriX uses 1800 seconds.

Limitations

• Preview environments are a Prime-only feature.
• The current implementation uses the GitHub pull request generator.
• Preview environments deploy from the pull request commit, not from Kargo freight or promotion stages.
• The application chart must be safe to deploy into an isolated preview namespace.
• Hub-and-spoke preview environments require correctly labelled Argo CD cluster secrets and a configured destinationCluster.