---
title: "Deploys"
description: "Deploy from your machine or from GitHub Actions with a per-app token, and roll back."
canonical_url: "https://docs.dev.lightdrop.cloud/guides/deploys"
---
# Deploys

> Deploy from your machine or from GitHub Actions with a per-app token, and roll back.

`wervt deploy` builds the app, uploads it to the control plane, migrates its database and
activates the new release. Each release records what was deployed: the commit, branch, commit
message and who deployed it, from git or from GitHub Actions, along with the bundle's size and the
migrations its deploy ran. The dashboard's **Deployments** page and `wervt releases <app>` show
them, and failed deploys too: a release that didn't start or failed its checks, and a deploy that
never became a release (a broken bundle, a failing migration) with its error.

```bash
pnpm exec wervt deploy                 # from the app's directory
pnpm exec wervt releases my-app        # newest first, with commit, author, size and migrations
pnpm exec wervt rollback my-app        # the release before the active one
pnpm exec wervt activate my-app <id>   # any kept release
```

The last 5 releases are kept. Rolling back doesn't revert migrations: an older build must work with
the current schema.

A migration the running release can't live with needs a moment without visitors:
`wervt deploy --maintenance` shows the [maintenance page](https://docs.dev.lightdrop.cloud/guides/maintenance) until the new release
runs.

## Audit log

The control plane records who changed what: deploys and failed deploys, rollbacks and activations,
deleted apps, access and member changes, maintenance mode, invites, env variables (the keys, never the values),
deploy and agent tokens, accounts and CLI logins. The dashboard shows it under **Audit Log**, for
all apps or one, and so does the CLI:

```bash
pnpm exec wervt audit                           # everything you may see, oldest first
pnpm exec wervt audit my-app --action 'deploy*' # one app's deploys
pnpm exec wervt audit --json --limit 500        # one JSON object per line
```

Admins see every entry; everyone else sees their apps' entries and their own account's. The log
lives in `<apps>/.audit/` on the server, so it outlives log retention and deleted apps.

## A release that doesn't start

After activating a release, the deploy starts it and sends it one request, the same way the app
starts for its first visitor. If it doesn't start (an error while the server loads, a missing
module, no answer within 60 seconds, or a 5xx answer), the app goes back to the release before,
and the deploy fails with the error:

```text
▲  Release 20261006213058-7dc906 didn't start
│
│  InvalidWorkerResponse: event loop error: Error: boom at startup
│
●  my-app is back on 20261006212843-58e25c.
```

`wervt deploy` exits with 1, so a GitHub Actions run fails too. The failed release stays in the
list, marked **Didn't start** on the **Deployments** page with its error. Its migrations stay
applied, like with a rollback. A first deploy has nothing to go back to, so it stays active and the
deploy fails.

## Page checks

Once the release started, the deploy requests `/` as a visitor who isn't signed in. A 5xx means the
page is broken (an error while rendering, a failing query), and the deploy reports it with the
first error the release logged:

```text
■  Release 20261012205519-568063 started, but failed: / (500)
│  TypeError: Cannot read properties of undefined (reading 'title')
▲  It stays active. Fix it or run `wervt rollback my-app`.
```

The release stays live, since other pages may work, but `wervt deploy` exits with 1, so CI fails.
Redirects and 4xx answers pass: a private app that sends visitors to the login is fine.

```bash
pnpm exec wervt deploy --check /,/about,/api/health   # these pages instead of /
pnpm exec wervt deploy --check=                       # no checks at all, shapes included
pnpm exec wervt deploy --rollback-on-fail             # go back to the release before on a failure
```

Up to 10 paths. The checks see only what an anonymous visitor sees: pages behind a sign-in answer
with whatever the app does without a user, even in a private app. A [`useShape`](https://docs.dev.lightdrop.cloud/api/use-shape)
whose route requires a user renders no rows then, without an error.

### Shape checks

Each [shape route](https://docs.dev.lightdrop.cloud/guides/live-data) in `server/api/shapes/` gets a request too, for its initial
snapshot, the way `useShape` starts. A page can render fine while Electric refuses a shape, for
example right after a migration added a column it doesn't know yet, so a shape also fails when Electric
answers **400**, along with 5xx and no answer. The deploy shows Electric's reason:

```text
■  Release 20261013091204-1f2a3b started, but failed: shape /api/shapes/todos (400)
│  {"message":"Invalid request","errors":{"columns":["The following columns are not found on the table: done"]}}
```

401, 403 and 404 pass: a shape that checks the session answers that way to an anonymous request,
so routes behind a sign-in only show that they load. So does a 400 from the route itself: the check
sends no query parameters, so a route that requires one rejects it before it reaches Electric, and
only shows that it loads. Routes with a dynamic segment
(`boards/[id].get.ts`) are skipped, there is no id to ask for. The body isn't read, so a shape of a
big table costs little more than its status. `@wervt/nuxt` lists the routes in
`server/wervt-shapes.json` when it builds; apps built with an older version deploy without shape
checks. `--check=` turns them off along with the page checks.

## Open tabs

A tab opened before a deploy keeps running the old release. Apps check for a new one every minute
and whenever the tab comes back to the foreground (a phone unlocked, a window focused), and then
show a small banner: **A new version is available · Reload**. Nothing reloads on its own, so no
one loses what they were typing; the next navigation inside the app loads the new release anyway.

For your own design, turn the banner off and use the state:

```ts [nuxt.config.ts]
wervt: { updates: 'manual' }, // false: no check at all
```

```vue
<script setup lang="ts">
const { available, reload } = useWervtUpdate()
</script>

<template>
  <UBanner v-if="available" title="A new version is available" :actions="[{ label: 'Reload', onClick: reload }]" />
</template>
```

## From GitHub Actions

Apps created with `create-wervt` come with `.github/workflows/deploy.yml`, which deploys on every
push to `main`. It needs a **deploy token**: it can deploy its app and its previews, read their
info and delete previews, and nothing else (no env, access, database, logs or other apps).

1. Create a token, in the dashboard (app > **Deployments** > **Deploy tokens**) or with the CLI:```bash
wervt tokens my-app --create github
```

<br />

The token is shown once. wervt only stores its hash.
2. In the GitHub repository, under **Settings > Secrets and variables > Actions**, add the token as
the secret `WERVT_TOKEN` and the control plane URL as the variable `WERVT_URL`.
3. Push to `main`. The run shows up as a `production` deployment on GitHub, linked to the app, and
the release links back to the run.

```bash
wervt tokens my-app                    # list: id, name, created, last used
wervt tokens my-app --revoke <id>
```

For an app created before the workflow existed, copy `.github/workflows/deploy.yml` from a new app
(`pnpm create wervt tmp --no-install`), add `@wervt/cli` as a dev dependency and set
`packageManager` in `package.json` (the workflow installs that pnpm version).

## Previews

A preview is a throwaway copy of an app at `<app>--<name>`, like one per pull request. New apps
come with `.github/workflows/preview.yml`: every pull request is deployed to
`https://my-app--pr-<number>.<domain>` with the same `WERVT_TOKEN`, shows up as a `preview`
deployment on the pull request, and is deleted when the pull request is closed or merged.

```bash
wervt deploy --preview pr-12                       # what the workflow runs
wervt deploy --preview try-checkout                # a preview without a pull request
wervt delete --preview pr-12                       # deletes it with its data
wervt env my-app --preview --set NUXT_API_URL=…    # preview variables, see below
```

- **Data**: each preview has its own database and files, empty apart from its migrations. Seed it
with `wervt tasks my-app--pr-12 --run db:seed`.
- **Access and members**: those of the app. Whoever manages the app manages its previews.
- **Env**: the app's variables, with its **preview variables** on top (dashboard: app >
**Environment Variables** > **Preview variables**, or `wervt env --preview`). Use them for
sandbox API keys or a staging backend.
- Settings are copied with each deploy, so a change to the app reaches a preview with its next
deploy. They can't be changed on the preview itself.
- An app can have up to 10 previews. They don't count against the account's app limit. Deleting
the app deletes its previews.
- Pull requests from forks get no preview: GitHub doesn't give their runs the secrets, and their
code shouldn't see the app's env.

## Tokens

<table>
<thead>
  <tr>
    <th>
      Token
    </th>
    
    <th>
      Can
    </th>
    
    <th>
      For
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      Admin
    </td>
    
    <td>
      everything
    </td>
    
    <td>
      the dashboard
    </td>
  </tr>
  
  <tr>
    <td>
      CLI session
    </td>
    
    <td>
      everything, revocable per machine
    </td>
    
    <td>
      you, via <code>
        wervt login
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      Read
    </td>
    
    <td>
      app info, releases and logs of every app
    </td>
    
    <td>
      agents debugging an issue
    </td>
  </tr>
  
  <tr>
    <td>
      Deploy (app)
    </td>
    
    <td>
      deploy one app and its previews
    </td>
    
    <td>
      CI
    </td>
  </tr>
</tbody>
</table>

## Signing in the CLI

```bash
wervt login --url https://api.example.com
```

The CLI shows a one-time code and opens the dashboard's **Settings** page. Enter the code there and
approve: the machine gets its own admin session, saved in `~/.config/wervt/config.json`. The
dashboard lists signed-in machines and signs them out. Codes expire after 10 minutes, and the code
is typed in rather than sent in a link, so a login can't be approved by clicking a link someone else
sent. `wervt login --url … --token …` saves a token directly (a read token, or for scripts).


## Sitemap

See the full [sitemap](https://docs.dev.lightdrop.cloud/sitemap.md) for all pages.
