# Deploy an app

Start a deployment of an app, wait for it to go live, follow its build log, or stop it.

A deployment runs the app's current source and settings. Replace app-id with the app's id
and deployment-id with the deployment's id.

## Prerequisites

- Permission for `deploy:DeployApp` on the app. Following a repository build's log needs
  `deploy:GetBuildLogs`.
- In the console, also `deploy:DescribeApp` to open the app's page (without it the page is not
  found).

## Start a deployment

**Console**
1. Open the app.
2. Choose **Deploy** in the app's header. The button is unavailable while another deployment is in
   flight (cancel it under **Deployments**, or wait), and without `deploy:DeployApp`.
3. The **Deployments** tab opens on the new deployment's **Activity**, which follows it as it runs.

**CLI**
```sh
dcloud deploy apps deploy app-id --wait --timeout 20m
```

`--image` deploys another image for this deployment only; the app's configured image is
unchanged. See [Deploy from GitHub Actions](deploy-from-github-actions.md) for every flag and exit
code.

**API**
```http
POST /deploy/api/apps/3f1c2b4a-5d6e-4f70-8a91-b2c3d4e5f601/deployments
{ "trigger": "manual", "reason": "Release 1.4.2" }
```

`imageRef` deploys that image this once without changing the app; an image in your registry is
resolved to its digest first. `gitCommitSha` names the commit a repository app deploys. Then call
`GET /deploy/api/deployments/deployment-id/wait` until the answer is terminal.

**Terraform:** not available. A deployment is an action, not a resource: creating an `dcloud_app` does not deploy it.

`reason` is shown on the deployment next to who started it. The request is refused with `409` while
the app is being deleted, and with `400` for an app with pooled hosting, which deploys the bundles
its CI uploads. A pooled app can have a Postgres database on its pool host: see
[Use a database on the pool host](use-a-pool-host-database.md).

## Follow the build log

While a repository build runs, the builder sends its log to the platform every two seconds, and the
deployment's **Activity** shows it live under **Build log**. It stays with the deployment after the
builder is deleted (until the deployment itself is deleted), with colours stripped and credentials
in URLs masked; after 8 MiB the rest is not kept. A build that fails ends the deployment at once,
not after the 15-minute build limit.

```sh
dcloud deploy deployments build-log deployment-id
```

Pass the previous answer's `next` as `--after` to follow it; `done` says no more lines will come,
and `exitCode` is the build script's exit status. Reading the build log is a sensitive read: it is
audited, and the ReadOnly policy does not include it.

## Stop a deployment

On the deployment's **Activity**, choose **Cancel**, then **Cancel deployment** in **Cancel
generation <n>?**, or:

```sh
dcloud deploy deployments cancel deployment-id
```

The pipeline stops at the end of the step it is in and the deployment is recorded as failed with
your name on it; the generation before it keeps serving. A throwaway build machine is removed by
the next cleanup sweep, within about ten minutes. Cancelling needs `deploy:DeployApp`; a deployment
that has already finished cannot be cancelled (`409`, `This deployment is already live, so there is
nothing left to stop.`).

## Result

The deployment goes `live` and the app's domains serve the new generation, or it ends `failed` with
its cause as the last line of **Activity** and the previous version still serving. See
[Deployments](deployments.md) for every status.

## Related

- [Turn on deploy on push](turn-on-deploy-on-push.md)
- [Roll back a deployment](roll-back-a-deployment.md)
- `deploy.deployments.create` · `dcloud deploy deployments create`
