Set Up Preview Deployments

Preview deployments create a temporary environment for every non-production branch, giving you a live URL to review changes before merging.

Enable preview environments

Preview deployments are controlled at the project level.

1. Open your project in the dashboard
2. Go to Settings
3. Find Preview Environments and toggle it on
4. Click Save

Once enabled, any push to a branch that is not the project's main branch (usually main or master) will automatically create a preview environment and deploy to it.

Run previews on-demand

By default, every preview environment runs 24/7 just like production. You can instead have each newly created preview start in on-demand mode, where it scales to zero when idle and wakes on the next request — so a stack of stale feature-branch previews stops consuming resources.

Under Settings > General, below the Enable Preview Environments switch, you'll find:

The on-demand toggle is disabled until preview environments are enabled, and the two timeout inputs only appear once on-demand is turned on. Both inputs are validated client-side against the same ranges the backend enforces.

You can also set this through the project-settings update API. The UpdateProjectSettingsRequest body accepts three optional fields:

curl -X POST "https://your-temps-instance/api/projects/{project_id}/settings" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "preview_envs_on_demand": true,
    "preview_envs_idle_timeout_seconds": 300,
    "preview_envs_wake_timeout_seconds": 30
  }'

If a timeout falls outside its valid range, the request is rejected with a validation error (for example, preview_envs_idle_timeout_seconds 30 is not in valid range (60-86400)).

How preview branches work

When a push arrives on a non-main branch:

1. Temps checks if a preview environment already exists for that branch
2. If not, it creates one — the environment is named after the branch (e.g. feature/login becomes the feature-login environment)
3. The application is built and deployed to that environment
4. A unique URL is generated for the preview

If the branch is pushed again, Temps redeploys to the same preview environment rather than creating a new one. If a previously deleted branch is pushed again, Temps restores the soft-deleted environment.

Preview URLs

Preview deployments get URLs in the format:

https://{project-slug}-{environment-slug}.{preview-domain}

For example, if your project is my-app and the branch is feature/login, the preview URL would be:

https://my-app-feature-login.yourdomain.com

Each individual deployment within the preview also gets its own URL:

https://{deployment-slug}.{preview-domain}

These per-deployment URLs let you compare different versions of the same branch.

Control which variables are included

Not all environment variables should be available in preview deployments. For example, you might want to keep production API keys or payment processor credentials out of previews.

Each environment variable has an Include in Preview toggle:

1. Go to your project's Environment Variables page
2. For each variable, check or uncheck Include in Preview
3. Variables with this toggle off will not be injected into preview environments

When creating a new environment variable via the API, set include_in_preview: false to exclude it:

curl -X POST "https://your-temps-instance/api/projects/{project_id}/env-vars" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "key": "STRIPE_SECRET_KEY",
    "value": "sk_live_...",
    "environment_ids": [1],
    "include_in_preview": false
  }'

Preview comments on pull requests

When a deployment runs for a branch that has an open GitHub pull request or GitLab merge request, Temps posts a single sticky comment on that PR/MR and updates the same comment in place as the deployment progresses — it never spams a new comment per build. This works identically on GitHub and GitLab.

The comment is keyed by a hidden HTML marker scoped to the project and environment:

<!-- temps-preview:project=N:env=N -->

On each update, Temps finds the existing comment carrying that marker and edits it; if none exists, it creates one. The comment body reflects the current phase of the deployment:

When a deployment is cancelled — from the dashboard or via the API — Temps updates the sticky comment to the cancelled state. Prior to this, cancelling a deployment would leave the comment stuck on 🚧 Deploying preview indefinitely. The cancelled body includes the commit SHA so it is clear which revision was stopped.

Required token scopes

For Temps to post comments, the connection needs write access to pull requests:

Newly created GitHub Apps request pull_requests:write automatically. An existing GitHub App installation that predates this and lacks the scope will hit a 403 — Temps logs it and skips the comment, but you'll need to upgrade the app's permissions to get sticky comments.

Access preview URLs

Find the URL for any preview deployment:

1. Open your project in the dashboard
2. Click Environments in the sidebar
3. You will see all environments listed — preview environments are marked with a Preview badge
4. Click on a preview environment to see its URL and deployment history

Alternatively, on the Deployments page, each deployment entry shows its environment name and a direct link to the live URL.

Create environments manually

Auto-created previews cover feature branches, but you can also create environments by hand for long-lived branches like staging or develop:

1. Go to your project's Environments page
2. Click New Environment
3. Enter a name (e.g. staging)
4. Select the branch it tracks (e.g. develop)
5. Configure replicas and resource limits (optional)

Manual environments behave like auto-created previews but are never soft-deleted when the branch is removed.

Per-environment overrides

Each environment can override the project-level deployment configuration:

Notify external systems with webhooks

Temps can fire outbound webhooks when a deployment changes state, so you can post a message to Slack, Discord, or any HTTP endpoint when a preview goes live or fails:

1. Go to Settings > Webhooks
2. Add a webhook URL
3. Select the deployment events you care about

The available deployment events are:

Each deployment payload carries the project_name, environment, branch, commit_sha, commit_message, status, and the live url — enough to build a meaningful notification.

Clean up stale previews

Preview environments accumulate over time as branches are created. To clean them up:

1. Go to Environments in your project
2. Find the preview environment you want to remove
3. Click the Delete button (or use the actions menu)

Deleting a preview environment:

• Stops and removes the running containers
• Soft-deletes the environment record (it can be restored if the same branch is pushed again)
• Does not delete the Git branch

You can also tear down individual deployments without deleting the entire environment. On the Deployments page, use the Teardown action on any deployment to stop its container and free resources while keeping the environment available for future pushes.

Troubleshooting

Preview not created after a push

• Verify that Preview Environments is toggled on in project settings
• Confirm the push targets a branch other than the project's main branch
• Check your Git provider's webhook delivery logs to confirm Temps received the push

Preview URL returns 404

• The deployment may still be building — check the Environments tab for its status
• If you serve previews from a custom domain, make sure a wildcard DNS record (for example *.yourdomain.com) points at your Temps server so every preview subdomain resolves

Variables missing in a preview

• Confirm the variable has Include in Preview enabled
• Variables are copied when the preview environment is first created. A variable added afterwards is not retroactively injected into existing previews — add it to the preview environment or recreate the preview