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

# promote

> floo promote: publish the live dev deploy to prod.

For your GitHub repository, publish a GitHub release to deploy its commit to prod once it is live in dev. For a floo-hosted project or an app with no repository, use `floo promote`. See [Production environments](https://getfloo.com/docs/guides/environments.md) for the release flow.

[`floo deploys --env prod`](https://getfloo.com/docs/cli/deploys) lists prod deploys with the release each one shipped: tag, number, who promoted it and the image.

## floo promote

Release the latest live dev deploy to prod for a [floo-hosted project](https://getfloo.com/docs/cli/deploy.md) or an app with no repository. For a floo-hosted project, floo also publishes a GitHub release on its repository. An app connected to your own GitHub repo is refused with `PROMOTE_USE_GITHUB_RELEASE`. The command returns the tag and release URL; `floo deploys --app my-app --env prod` tracks the background deploy and shows the release it shipped.

```bash theme={null}
floo promote --app my-app
```

### What happens during promote

1. **Image selection.** Promote deploys the images from the latest live dev deploy. It rebuilds only when the prod environment has a build-time env var (`VITE_*`, `NEXT_PUBLIC_*`, or `REACT_APP_*`); then each service is built again from the source deploy's archived source with the prod values as build arguments.
2. **Migrations.** Each declared `migrate_command` runs as a one-off job with prod env vars before traffic shifts. A failure stops promotion and leaves the previous live revision serving. Keep the old code compatible with schema changes through [expand-then-contract migrations](https://getfloo.com/docs/guides/postgres.md#schema-portability-across-dev-and-prod). `floo deploy --rebuild --skip-migrations` has no effect on promote.
3. **Routes.** floo updates routes on the shared app host and per-service hosts, including routes affected by a service rename.
4. **Access grants.** The gateway is granted invoke access on public services, and the app identity on internal services.

### Flags

| Flag | Description |
| - | - |
| `--app APP` | App name or UUID |
| `--tag TAG` | Release tag (auto-generated if omitted, e.g., `v1.2.1`) |

### Examples

```bash theme={null}
# Promote with auto-generated tag
floo promote --app my-app

# Promote with explicit tag
floo promote --app my-app --tag v2.0.0

# Agent workflow: promote and extract tag
floo promote --app my-app --json 2>/dev/null | jq -r '.data.tag'
```

### JSON output

```json theme={null}
{
  "success": true,
  "data": {
    "tag": "v1.2.1",
    "release_url": "https://github.com/<managed-owner>/my-app/releases/tag/v1.2.1"
  }
}
```

`release_url` is set for floo-hosted projects and `null` for an app with no repo.

***

## rollback

Use [`floo rollback`](https://getfloo.com/docs/cli/deploys#floo-rollback-app-deploy_id) to restore a previous live deploy's image without rebuilding:

```bash theme={null}
floo rollback my-app d1e2f3g4
```

The app and deploy ID are positional arguments. `--preflight` previews the operation; `--yes` is required in non-interactive runs. Rollback keeps current environment configuration and does not undo database migrations.

***

## Errors

| Code | Meaning |
| - | - |
| `NOT_AUTHENTICATED` | Run `floo auth login` first |
| `APP_NOT_FOUND` | No app with that name or ID |
| `PROMOTE_USE_GITHUB_RELEASE` | 409: the app uses your own GitHub repo. The CLI suggests the exact `gh release create <tag> --repo <owner/repo>` command |
| `NO_DEV_DEPLOY` | Deploy to dev first before promoting |
| `NO_PROMOTABLE_SERVICES` | The latest live dev deploy has no image to promote |
| `RELEASE_TAG_EXISTS` | A release with that tag already exists. Use a different `--tag` |


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