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

# Deployments and releases

> Understand triggers, deployment stages, health-based promotion, and rollback.

A deployment is one attempt to put an app or resource into service. Towbar records its trigger, immutable inputs, progress, duration, and final result separately from Repository sync history.

<div className="towbar-doc-screenshot">
  <div className="towbar-product-light">
    <img src="https://mintcdn.com/avgeek/7IKQY5hBmeQaVMw0/assets/release-v2/deployments-light.jpg?fit=max&auto=format&n=7IKQY5hBmeQaVMw0&q=85&s=e1281e1337eb58b2992837f3e617a69d" alt="Filter deployment history by status, trigger, and workload." width="1280" height="1210" loading="lazy" data-path="assets/release-v2/deployments-light.jpg" />
  </div>

  <div className="towbar-product-dark">
    <img src="https://mintcdn.com/avgeek/7IKQY5hBmeQaVMw0/assets/release-v2/deployments-dark.jpg?fit=max&auto=format&n=7IKQY5hBmeQaVMw0&q=85&s=4b4b5479d11f44c5d82360e51859d61a" alt="Filter deployment history by status, trigger, and workload." width="1280" height="1210" loading="lazy" data-path="assets/release-v2/deployments-dark.jpg" />
  </div>

  <p>Filter deployment history by status, trigger, and workload.</p>
</div>

## Browse deployment history

Use the Deployments page sidebar to filter by workload type, environment, status, trigger, or server. Sort by request time or workload name. Filters and sorting apply to the full history before pagination, and the URL preserves your selection.

On mobile, open **Page menu** to access the filters.

## Deploy manually

Open an app or resource and choose **Deploy**. The server must be prepared and trusted, and required credentials must be configured. Follow the queued operation through its recorded stages; a queued request is not a completed deployment.

```mermaid theme={"system"}
flowchart LR
  Queue[Queue] --> Image[Build or pull image]
  Image --> Candidate[Start candidate]
  Candidate --> Health[Check health]
  Health --> Promote[Promote release]
```

The details vary by workload and configured hooks. Use the operation's actual stage output when diagnosing a failure.

## Automatic deployments

Apps and resources are manual unless `autoDeploy` is enabled. `autoDeploy: true` treats commits as deployment inputs. Apps can narrow their inputs with repository globs:

```yaml title=".towbar/apps/web.app.yml" theme={"system"}
id: web
autoDeploy:
  inputs:
    - package.json
    - pnpm-lock.yaml
    - apps/web/**
environments:
  production: {}
```

This is a fragment, not a complete manifest. Towbar compares selected file identities and configuration to decide whether to queue work. An incomplete Git tree is treated as changed. Include every file that can affect the built app, including shared libraries and build configuration.

Use the Repository's pause controls to stop automatic deployment during maintenance. Saving a secret does not enqueue a deployment; deploy explicitly when you want the new value to take effect.

## Deployment hooks

App hooks run commands around deployment. Add hook configuration under the app:

```yaml theme={"system"}
hooks:
  preDeploy:
    command: ["node", "scripts/migrate.js"]
    timeoutSeconds: 120
  postDeploy:
    command: ["node", "scripts/warm-cache.js"]
    timeoutSeconds: 60
```

A pre-deploy failure stops deployment before promotion. A post-deploy failure is reported as a warning after promotion. Hooks receive their own stage-specific secrets. Design commands so retries are safe and schema changes remain compatible with the previous release.

## Read the final result

| Result                  | Meaning                                                            |
| ----------------------- | ------------------------------------------------------------------ |
| Succeeded               | Deployment completed successfully                                  |
| Succeeded with warnings | The release was promoted, but a later step needs attention         |
| Failed                  | A required stage failed; inspect the last stage and active release |
| Cancelled               | The operation stopped through cancellation                         |

Durations advance while work is ongoing and stop at the final timestamp. The latest runtime health can still change after deployment succeeds.

## Inspect image vulnerabilities

For opted-in apps, open **Vulnerabilities** in the deployment’s secondary sidebar to inspect the immutable image’s scan state, severity totals, and package findings. **Monitor → Vulnerabilities** collects findings across the workspace. A successful deployment can still have vulnerabilities; a scan failure does not change deployment health. See [Vulnerability scanning](/docs/vulnerability-scanning) for setup and result interpretation.

## Roll back an image

Use a retained release when you need to return to a previous image. Rollback uses current runtime secrets, so it does not restore revoked credentials. It also does not undo database writes or schema migrations. Check compatibility before rolling back an app that ran a migration.

Database recovery is a separate [restore operation](/docs/restores). For build or startup failures, follow [Troubleshooting](/docs/troubleshooting).