Cloudgate
Start free trial
MenuClose

Preview deployments

A preview deployment is a copy of one git-sourced Application built from another branch, on its own address. Use it to see a change running before it reaches production, for every pull request or on request.

Git-sourced ApplicationsMembers can manage previews

A preview is not a Service and not an Environment. It is a copy of one Application, built from a branch, that shares the parent’s storage and Environment and answers on its own host under a wildcard Domain.

There are two kinds:

  • Pull-request preview: opened by a pull request against the tracked branch, one per pull request, removed when it closes. GitHub-sourced Applications only.
  • Requested preview: asked for by a person or an Agent for any branch, and torn down when it expires.

What you can do

  • Build a preview for every pull request, up to a limit you set.
  • Allow requested previews, for example so an AI agent can show you its fix running.
  • Give previews their own variables and build arguments.
  • Extend, redeploy or expire a requested preview; redeploy or tear down a pull-request preview.

Set up previews

  1. Point a wildcard at the Server

    Create a DNS record for a wildcard host, for example *.preview.northwind.example, pointing at the Application’s Server. It must resolve before previews can be reached.

  2. Open Preview settings

    Open the Application, then Previews > Preview settings.

    cloudgate.octabyte.app/applications/…/previews
    Settings at the top, open previews below.

  3. Fill in the settings

    • Wildcard host: the host you pointed above. You can also issue the wildcard certificate through DNS-01 with Let’s Encrypt.
    • Container port: the port the app listens on.
    • Preview variables: replace the Application’s variables in previews. Left empty, previews use production’s.
    • Preview build arguments: build arguments for preview builds.
    • Build a preview for every pull request and Most previews at once.
    • Allow requested previews and Most requested previews at once (3 by default, counted apart from pull-request previews).

  4. Save

    Open a pull request against the tracked branch. Its preview appears in the list with its address once built.

Ask for a requested preview

A requested preview is created through the API or MCP, not from a console button:

  • An Agent calls create_preview with the Application and branch, and optionally a lifetime in minutes. See MCP tools.
  • A script calls POST /applications/{applicationId}/preview-deployments. See the API reference.

Whoever may deploy the Application can ask, but only while Allow requested previews is on. Each call makes a new preview, even for the same branch.

Extend, redeploy or expire a requested preview

The Requested previews list shows each preview’s branch, who asked for it, when it expires and its latest build.

  • Extend sets a new expiry a number of minutes from now. It replaces the window; it does not add to it.
  • Redeploy builds the branch again. It never moves the expiry.
  • Expire now tears it down at once.

A requested preview lives 60 minutes by default. The longest a request may ask for is the instance’s Requested preview lifetime, 24 hours unless the operator changed it (self-hosted, Settings > Instance).

What you cannot do

  • Pull-request previews need a GitHub source.
  • Create a requested preview from the console; use the API or MCP.
  • Extend a preview that has already expired; ask for a new one.
  • Turning Allow requested previews off refuses new ones; previews already running stay until they expire.
  • Turning on requested previews needs permission to update the Application, which no Agent role has.

Questions

Do previews use my production database?

They share the parent Application's storage and Environment, so yes, unless you set Preview variables that point them somewhere else.

Can I create a requested preview from the console?

No. The console lists, extends, redeploys and expires requested previews, but you create one through the API or an Agent's create_preview tool.

How long does a requested preview live?

60 minutes unless the request asks for longer, up to the instance maximum, 24 hours by default. Extend sets a new window starting now.

Which git providers support pull-request previews?

GitHub only. Requested previews work for any git source.

Something missing or wrong on this page? Email support@octabyte.io, or start a free trial and try it in the console.