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 anexpires_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.
- 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.
Creating a preview from the API
To create a preview deployment programmatically, setpreview 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.Listing previews by label
Thepreview_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.
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.
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.
Delete Preview
Select Delete Preview to immediately delete the deployment and release its cluster resources. A confirmation dialog appears before the teardown proceeds.
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 anexpires_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:- On push to a feature branch, build the agent image
- Deploy the image as a preview with
preview_labelset to the branch name - Poll the deployments endpoint to confirm the preview is healthy
- Run integration tests against the preview endpoint
- On merge to main, deploy to production (the preview expires naturally or can be torn down)
Next steps
- API and SDK: full request and response schemas for preview deployment fields
- CI/CD with Gitea Actions: workflow templates for automated builds
- Secrets: store and reference credentials used during deployments