Skip to main content

Overview

Preview deployments are ephemeral Helm releases designed for testing agent changes in isolation before promoting to production. Each preview gets its own unique Helm release name, so you can run multiple previews simultaneously (one per branch, PR, or experiment) without interfering with your production deployment or with each other. Previews are always time-boxed. Every preview deployment has an expires_at timestamp, defaulting to 8 hours from creation if you do not specify one. When the TTL expires, a background cleanup process automatically tears down the deployment and releases its cluster resources. You can also tear down a preview manually at any time, or promote it to a permanent production deployment when you are satisfied with the results.

How previews differ from production

The unique Helm release name is what makes simultaneous previews possible. Production deployments reuse a stable release name, so deploying a new version replaces the previous one. Preview deployments append a deployment ID suffix to the release name, giving each preview its own set of Kubernetes resources.
Preview deployments are supported through the SGP dashboard UI, the API/SDK, and the Gitea CI/CD workflows: a /deploy-preview comment on a pull request, a manual run of cloud-preview-deploy.yaml, and the eval workflows. The sgpctl CLI does not currently support creating preview deployments.

Creating a preview from the UI

From any successful build’s detail page, click Create deployment (or use the chevron dropdown and select Create preview deployment). In the deploy modal, toggle Preview deployment to ON.
Deploy modal with preview toggle enabled, showing preview label field and TTL picker
When the preview toggle is enabled, two additional fields appear:
  • Preview label: an optional free-text label (max 30 characters) for grouping related previews. Use your branch name, PR number, or any identifier that helps you find this preview later. In the screenshot, the label is set to pr-495.
  • TTL: how long the preview should live before automatic teardown. The default is 8 hours.
Click Deploy preview to create the deployment. The preview appears in the Deployments list on the build detail page with a Preview badge and an “Expires in X hours” indicator.

Creating a preview from the API

To create a preview deployment programmatically, set preview to true in your POST /v5/agentex/deployments request. You can optionally include a preview_label and a custom expires_at timestamp. As with any deployment, environment_config is one entry from under environments: in your environments.yaml, not the whole file.
Preview deployments always have an expires_at value. If you omit it, the API defaults to 8 hours from the time of creation. The timestamp must be timezone-aware (include Z or a UTC offset like +00:00) and must be in the future.
Validation rules for preview-specific fields:

Listing previews by label

The preview_label field is a non-unique grouping label. Multiple preview deployments can share the same label, which is useful when you redeploy the same branch multiple times. To find the latest preview for a given label, query the deployments list endpoint with the preview_label filter, sort_order=desc, and limit=1. Without sort_order=desc, the list is sorted oldest first.
This pattern is useful in CI pipelines. After deploying a preview, your pipeline can poll this endpoint with the branch name as the label to check deployment health before running integration tests.

Managing preview deployments

Every deployment row in the Deployments list has a three-dot actions menu with Redeploy, View Details and Copy Deployment ID. Preview rows also have Promote to Production and Delete Preview.
Three-dot actions menu on a preview deployment showing View details, Copy deployment ID, Redeploy as preview, Promote to production, and Tear down preview
The available actions are:

Promote to Production

Select Promote to Production to make the preview the agent’s production deployment. The menu shows this action only for healthy previews.
Promote to production confirmation dialog
Promotion is an atomic cutover: production traffic switches to the preview immediately. No new deployment is created, and the previous production deployment keeps running until the next production deploy replaces it.

Delete Preview

Select Delete Preview to immediately delete the deployment and release its cluster resources. A confirmation dialog appears before the teardown proceeds.
Tear down confirmation dialog
Once torn down, the deployment transitions to a terminal state and its Kubernetes resources are removed. This action cannot be undone. If you need the same configuration again, use Redeploy on a previous deployment or create a new preview from the build detail page.

Redeploy

Select Redeploy to open the deploy modal pre-filled with the deployment’s manifest and environment configuration. The modal opens with Deploy as preview off and an empty preview label, so to redeploy as a preview, turn the toggle on and enter the label again.

TTL and expiration

Every preview deployment has an expires_at timestamp that controls its lifetime. When you create a preview without specifying expires_at, the API defaults to 8 hours from the time of creation. In the SGP dashboard, preview deployments display an “Expires in X hours” badge so you can see at a glance how much time remains. As the TTL approaches, the badge counts down. When the expires_at time is reached, a background cleanup process automatically tears down the preview deployment and releases its cluster resources. You do not need to take any action. Expired previews are cleaned up automatically. If you need more time with a preview, create a new preview deployment with a longer TTL. You cannot extend the expires_at of an existing preview. The new preview can reuse the same preview_label so it remains easy to find via the API.
Automatic teardown is handled by a background process that runs periodically. There may be a short delay between the expires_at timestamp and the actual resource cleanup, but the preview will stop serving traffic at expiration.

CI/CD integration

Preview deployments work well in CI/CD pipelines for automated branch testing. A typical pattern is:
  1. On push to a feature branch, build the agent image
  2. Deploy the image as a preview with preview_label set to the branch name
  3. Poll the deployments endpoint to confirm the preview is healthy
  4. Run integration tests against the preview endpoint
  5. On merge to main, deploy to production (the preview expires naturally or can be torn down)
Here is a simplified workflow snippet showing the deploy and verify steps:
Set the preview_label to your branch name or PR number in CI. This makes it straightforward to look up the latest preview for any branch using the list endpoint with the label filter, and it keeps the SGP dashboard organized when multiple branches have active previews.

Next steps