> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sevalla.com/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> These are the docs for Sevalla, a platform for deploying applications, databases, static sites, object storage and load balancers. The dashboard is at https://app.sevalla.com.
> Bold text in steps is an exact dashboard label.
> To act on a Sevalla account, prefer the Sevalla MCP server (https://mcp.sevalla.com/mcp, see https://docs.sevalla.com/ai-agents/overview.md), then the Sevalla CLI (https://docs.sevalla.com/developer-tools/cli.md), then the REST API (https://api-docs.sevalla.com, OpenAPI spec at https://api.sevalla.com/v3/openapi.json).
> Every page index is at https://docs.sevalla.com/llms.txt.

# Preview apps

> Give every pull request its own short-lived application in a pipeline: turn preview apps on, set what each one runs, deploy branches by hand, and control when they're deleted.

A preview app is a short-lived application that a [pipeline](/pipelines/overview) creates from a pull request or a branch of the pipeline's repository, so you can try a change on its own URL before it merges. Preview apps live in the pipeline's preview stage, are redeployed on every push to their branch, and are deleted when their pull request closes.

## How preview apps work

When you turn on preview apps, the pipeline gets a preview stage, shown as the **Preview** column first on the board. You set once what every preview app gets: the repository, location, build strategy, processes, disks, TCP proxies and environment variables. Each preview app is then a regular [application](/applications/overview) built from those settings, with its own **Deployments**, **Logs** and other tabs.

| Event | What Sevalla does |
| - | - |
| A pull request opens (or reopens, on GitHub) | With **Automatically create preview apps for each pull request** on, creates a preview app from the pull request's branch and deploys its latest commit. Nothing happens if the pull request already has one. |
| You click **Create preview app** on a pull request | The same, by hand. |
| You deploy a branch with **Deploy preview app** | Creates a preview app for the branch, without a pull request. |
| Someone pushes to the branch | Redeploys every preview app of that branch. Automatic deployments are always on for preview apps. |
| The pull request is merged or closed | Deletes the preview apps of that pull request, whether they were created automatically or by hand. Branch preview apps stay. |
| No deployment for the chosen number of days | With **Delete stale preview apps automatically** on, deletes the preview app. Sevalla checks every 30 minutes. |
| You disable preview apps or delete the pipeline | Deletes every preview app of the pipeline. |

Each deployment of a pull request's preview app updates one comment on the pull request, on GitHub, GitLab and Bitbucket alike: **Preview deployments for** *the preview app*, with its status (deploying, ready, failed or cancelled), a **Visit preview** link once it's ready, the commit, the deployment ID and the application name. On GitHub, each deployment also shows as a GitHub deployment in the `Preview` environment.

### Names and addresses

A pull request's preview app is named `pr-<number>-` followed by the pipeline's name, and a branch preview app `branch-<branch>-` followed by the pipeline's name. Sevalla shortens the name to 27 characters and adds a random suffix, and serves the preview app on `<name>.sevalla.app`. For example, pull request #42 of the pipeline `storefront-a1b2c` becomes `pr-42-storefront-a1b2c-x7k2m.sevalla.app`.

Preview apps belong to the pipeline's project and run in the location of the preview settings.

### What preview apps cost

Preview apps are billed like any other application, for as long as they exist: see [Pricing](/billing/pricing). Three settings keep the cost down: [hibernation](#app-settings) (on by default) scales a preview app to zero when it gets no traffic, **Delete stale preview apps automatically** deletes forgotten ones, and the smallest instance size is the default for the web process.

## Before you begin

* A valid payment method. Without one, Sevalla refuses with `No valid payment method found. Add one at https://app.sevalla.com/billing/payment-methods to continue.`
* A [Git account](/git/overview) connected to your Sevalla user, with access to the repository the preview apps build from. Preview apps build from GitHub, GitLab or Bitbucket repositories, not from public repository URLs or Docker images.
* Permission to update applications in the pipeline's project (or company). Creating preview apps also needs permission to create applications.

## Enable preview apps

<Steps>
  <Step title="Open the settings">
    In the sidebar, click **Applications**, then click the pipeline. In the **Preview apps** card, click **Enable preview apps**, or open **Pipeline actions** (⋯) and click **Enable preview apps**.
  </Step>

  <Step title="Choose when preview apps come and go">
    In **Pull requests**, select **Automatically create preview apps for each pull request** to get one per pull request without clicking. Keep **Delete stale preview apps automatically** selected and pick how many days without a deployment make a preview app stale.
  </Step>

  <Step title="Pick the repository">
    In **App settings**, pick the **Git provider**. If your account isn't connected yet, click **Connect to** *provider* and authorize Sevalla in the new tab. Then pick the **Repository**.
  </Step>

  <Step title="Set the build and location">
    Pick the **Location** and the **Build type**, and adjust the build path or Dockerfile fields if your application isn't at the repository root. See [App settings](#app-settings).
  </Step>

  <Step title="Set what each preview app runs">
    In **Processes**, enter the web process's **Start command** and **Port**, and add a **Worker**, **Job** or **Cron** if the application needs them. Add disks, TCP proxies and environment variables in their sections if needed.
  </Step>

  <Step title="Turn them on">
    Click **Enable preview apps**.
  </Step>
</Steps>

<Frame>
  <img className="block dark:hidden" src="https://assets.sevalla.com/screenshots/light/pipeline-preview-enable.png" alt="The Enable preview apps sheet: App settings with Git provider, Repository, Location, Build type, Build path and Hibernation, then the Processes section" width="768" />

  <img className="hidden dark:block" src="https://assets.sevalla.com/screenshots/dark/pipeline-preview-enable.png" alt="The Enable preview apps sheet: App settings with Git provider, Repository, Location, Build type, Build path and Hibernation, then the Processes section" width="768" />
</Frame>

The **Preview** column replaces the **Preview apps** card, and each open pull request of the repository shows as a card with **Create preview app**. When you turn on automatic creation, new pull requests get a preview app from now on; pull requests that were already open get one only if you click **Create preview app**.

## Preview app settings

These settings apply to preview apps created after you save them. Preview apps that already exist keep the configuration they were created with: change one on its own tabs, or delete it and create it again.

### Pull requests

| Setting | What it does | Default |
| - | - | - |
| **Automatically create preview apps for each pull request** | Every new pull request gets a preview app, deleted when the pull request closes. | Off |
| **Delete stale preview apps automatically** | Deletes a preview app whose last deployment is older than the chosen time, from **After 1 day without any deploy** to **After 30 days without any deploy** (1, 2, 5, 14 or 30 days). Applies to pull request and branch preview apps. | On, 5 days |

### App settings

| Setting | What it does | Default |
| - | - | - |
| **Git provider** | GitHub, GitLab or Bitbucket. Changing it clears the repository. | The pipeline's provider |
| **Repository** | The repository preview apps build from, from your connected account. Use the refresh button after creating a repository. Required: `Repository is required`. | None |
| **Location** | Where preview apps run. See [Locations](/platform/locations). | The location closest to you |
| **Build type** | **Nixpacks**, **Railpack** (**Beta**), **Buildpacks** or **Dockerfile**. See [Builds](/applications/builds/overview). | **Nixpacks** |
| **Build path** | Folder to build, for every build type but Dockerfile | `.` |
| **Dockerfile path** and **Docker context** | For **Dockerfile** | `Dockerfile` and `.` |
| **Add buildpack** and **Buildpack order** | For **Buildpacks**: Node.js, Python, PHP, Java, Scala, Go and Ruby (`heroku/nodejs` and so on), in the order they run | None |
| **Hibernation** | Scales a preview app to zero when no HTTP requests arrive. It wakes on the next HTTP request, usually within 90 seconds; Sevalla holds that first request for up to about 3 minutes while it starts. Cron jobs keep running. Choose how long without requests: **Hibernate after 15 minutes of inactivity**, 1 hour, 6 hours, 24 hours or 48 hours. See [Hibernation](/applications/scaling#hibernation). | On, 15 minutes |

### Processes

Every preview app has one web process, named **Web process** by default, which you can't delete. **Worker**, **Job** and **Cron** add a [background worker, job or cron job](/applications/processes). Each process runs one instance.

| Field | Applies to | What it is | Default |
| - | - | - | - |
| **Name** | Every process | Required: `Required field` | **Web process** for the web process |
| **Start command** | Every process | The command the process runs, for example `npm start` | Empty |
| **Port** | Web | The port the web process listens on | `8080` |
| **Schedule** | Cron | Five cron fields, in UTC, for example `*/30 * * * *`. `Invalid cron` when it isn't valid. | None |
| **Start policy** | Job | **Before deployment**, **After successful deployment** or **After failed deployment** | **Before deployment** |
| **Resource** | Every process | The instance size. See [Instance sizes](/applications/scaling#instance-sizes). | **H1**, the smallest size, for the web process |

### Disks

A disk gives a web or worker process persistent storage. For each of these processes, turn on its switch, then set the **Mount path** (default `/var/lib/data`) and the **Size**. See [Persistent storage](/applications/disks).

### TCP proxies

A TCP proxy makes a web or worker process reachable over TCP. Click **Add TCP proxy**, pick the **Process**, enter the **Port** (1 to 65535, default `8080`), and turn on **Public** to reach it from the internet; off, it's private. A preview app can have up to 3 TCP proxies by default. See [Networking](/applications/networking).

### Environment variables

Click **Add variable** and enter a **Key** and **Value**, or click **Import .env**, or paste the content of a `.env` file into a key field. Every variable is available when the preview app builds and when it runs. A row with a value needs a key (`Key is required`); empty rows are dropped. Each preview app gets its own copy, which you can change on its **Environment variables** tab. See [Environment variables](/applications/environment-variables).

## Update preview app settings

<Steps>
  <Step title="Open the settings">
    On the pipeline board, open the **Preview** column's ⋯ menu, or **Pipeline actions** (⋯), and click **Preview app settings**.
  </Step>

  <Step title="Change them">
    Update any section. Changing the repository makes the next preview apps build from the new one.
  </Step>

  <Step title="Save">
    Click **Update preview settings**.
  </Step>
</Steps>

The next preview apps use the new settings. Existing preview apps don't change.

## Create a preview app for a pull request

On the pipeline board, find the pull request's card in the **Preview** column and click **Create preview app**. Use it for pull requests opened before you turned on automatic creation, or when automatic creation is off.

The card turns into the preview app's card, and its first deployment starts. When the deployment finishes, open the preview app from its address on the card, or from **Visit preview** in the pull request's comment. Sevalla refuses with `Pull request <number> not found` if the pull request is gone.

## Deploy a branch as a preview app

<Steps>
  <Step title="Open the Deploy preview app sheet">
    On the pipeline board, open the **Preview** column's ⋯ menu and click **Deploy preview app**.
  </Step>

  <Step title="Pick the branch">
    The **Repository** is the one in the preview settings. In **Branch**, pick the branch (`main` or `master` is preselected when it exists). Click the refresh button for branches pushed after the sheet opened.
  </Step>

  <Step title="Deploy">
    Click **Deploy preview app**.
  </Step>
</Steps>

<Frame>
  <img className="block dark:hidden" src="https://assets.sevalla.com/screenshots/light/pipeline-board-preview-deploy.png" alt="The Preview column's menu open with Deploy preview app, Preview app settings and Disable preview apps, next to two pull request cards with Create preview app" width="1352" />

  <img className="hidden dark:block" src="https://assets.sevalla.com/screenshots/dark/pipeline-board-preview-deploy.png" alt="The Preview column's menu open with Deploy preview app, Preview app settings and Disable preview apps, next to two pull request cards with Create preview app" width="1352" />
</Frame>

The branch preview app appears in the **Preview** column and deploys the branch's latest commit. It isn't tied to a pull request, so closing one doesn't delete it: delete it from its own [settings](/applications/settings), or let stale cleanup remove it. Sevalla refuses with `No commit found for branch <branch>` when the branch has no commits.

## Delete a preview app

Open the preview app from its card in the **Preview** column and delete it from its **Settings** tab, as any [application](/applications/settings). If its pull request is still open, the pull request's card comes back with **Create preview app**.

## Disable preview apps

<Warning>
  Disabling preview apps deletes every preview app of the pipeline permanently. You can't undo this.
</Warning>

<Steps>
  <Step title="Open the dialog">
    On the pipeline board, open the **Preview** column's ⋯ menu and click **Disable preview apps**.
  </Step>

  <Step title="Confirm">
    Check the list of preview apps that will be deleted, then click **Disable preview apps**.
  </Step>
</Steps>

The **Preview** column goes back to the **Preview apps** card, and pull requests stop getting their own app. Turning preview apps on again starts from new settings.

## API and CLI

| Task | API | CLI |
| - | - | - |
| Enable preview apps | [Enable pipeline preview](https://api-docs.sevalla.com/v3/pipelines/enable-pipeline-preview) | `sevalla pipelines preview enable <pipeline-id> --repo-url <url> --auto-create-app true` |
| Update the repository and pull request options | [Update pipeline preview settings](https://api-docs.sevalla.com/v3/pipelines/update-pipeline-preview-settings) | `sevalla pipelines preview update <pipeline-id> --stale-app-days 14` |
| Disable preview apps | [Disable pipeline preview](https://api-docs.sevalla.com/v3/pipelines/disable-pipeline-preview) | `sevalla pipelines preview disable <pipeline-id>` |
| Create a preview app for a branch or pull request | Not available. Use the [dashboard](#deploy-a-branch-as-a-preview-app). | Not available |
| See the preview stage and its settings | [Get pipeline](https://api-docs.sevalla.com/v3/pipelines/get-pipeline) | `sevalla pipelines get <id>` |

The API and CLI set the repository (`repo_url`), automatic creation (`auto_create_app`) and stale cleanup (`delete_stale_apps`, `stale_app_days`, 1 to 365 days). The app settings, processes, disks, TCP proxies and environment variables of preview apps are set in the dashboard only, so enable preview apps in the dashboard first.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.