Deployments
A deployment is an immutable, versioned bundle of XML fragments and value resources.
Deployments belong to the project — not to a channel — and are identified by a
version plus a revision. The platform assigns revisions automatically, counting
from 0 per version: every deploy of 1.0.0 mints the next revision in that version's
lineage (rev 0, rev 1, rev 2, ...). Nothing is ever overwritten.
Deploying stages a bundle; publishing makes it live on a channel. The two are separate steps, though the CLI offers to publish immediately after a successful deploy.
Deploy
Upload your project's UI resources and mint a new revision:
| Option | Abbr | Description |
|---|---|---|
--version |
-v |
Deployment version (defaults to the version in pubspec.yaml) |
--notes |
-n |
Deployment notes |
--publish |
-p |
Publish the new revision to this channel after deploying. The channel must already exist |
What Happens
- Verifies
xwidget>= 0.6.0 is listed as a dependency. - Creates a new cloud project if this is the first deploy from this directory (writes
xwidget_cloud.yamlto your project root). - Prompts for a version number if
--versionis not provided. Defaults to the version frompubspec.yaml. - Prompts for the fragments and values resource paths if not previously configured.
- Creates a tarball of the resources, uploads it, and mints the next revision for the version.
- Offers to publish the new revision to a channel — or, with
--publish <channel>, publishes it without asking. Decline and the deployment stays staged — you can publish it any time withxc cloud publish.
Redeploying an existing version never overwrites it — it mints the next revision. Channels serving an earlier revision are unaffected until you publish the new one.
Without a terminal (in CI, for example), deploy never prompts: pass --version, and
add --publish to go live in the same step. The named channel must already exist —
deploy validates it before uploading and fails otherwise, so a typo can't stage a
bundle it then can't publish. If the upload succeeds but publishing fails, deploy
prints the exact xc cloud publish command to finish the job and exits non-zero.
Version Format
Versions must match major.minor.patch, optionally followed by a pre-release
identifier (-beta, -rc.1, etc.) and/or a numeric build number (+42). The build
number, when present, is part of the version's identity: 1.0.0+41 and 1.0.0+42 are
different versions, each with its own revision lineage.
| Accepted | Not accepted |
|---|---|
1.0.0 |
1.0 |
2.1.0+42 |
v1.0.0 |
1.0.0-beta |
2.1.0+build.42 |
1.0.0-rc.1+7 |
0.0.1+hotfix |
The build number must be numeric — it maps to the Flutter build number in
pubspec.yaml's version: x.y.z+N.
Examples
# Interactive — prompts for version and paths, then offers to publish
$ xc cloud deploy
# Fully specified
$ xc cloud deploy -v 1.0.0
# With notes
$ xc cloud deploy -v 1.2.0 -n "Bug fix release"
# Deploy and publish in one step (the channel must already exist)
$ xc cloud deploy -v 1.2.0 --publish production
Publish
Point a channel at a deployment. Publishing is how a revision goes live — and because it only moves a pointer, it is also how you promote a tested revision to another channel or roll a channel back to an earlier revision. If the channel already serves the version, the pointer is repointed to the revision you specify.
| Option | Abbr | Description |
|---|---|---|
--workspace |
-w |
Workspace to use |
--project |
-p |
Project to use |
--channel |
-c |
Target channel to publish to |
--deployment-id |
-d |
Deployment to publish |
--version |
-v |
Deployment version to publish |
--revision |
-r |
Deployment revision to publish |
--yes |
-y |
Skip confirmation prompt |
Identify the deployment either by --deployment-id, or by --version plus
--revision. If options are omitted, the CLI walks you through selecting the version,
revision, and target channel interactively. You can create a new channel during the
process.
Examples:
# Interactive
$ xc cloud publish
# Make revision 2 of 1.0.0 live on staging
$ xc cloud publish -c staging -v 1.0.0 -r 2
# Promote: publish the same revision to production
$ xc cloud publish -c production -v 1.0.0 -r 2
# Roll back: publish the previous revision
$ xc cloud publish -c production -v 1.0.0 -r 1
Unpublish
Remove a channel's pointer for a version. Apps on that channel stop receiving the version's bundle; the deployment itself is untouched and can be published again at any time.
| Option | Abbr | Description |
|---|---|---|
--workspace |
-w |
Workspace to use |
--project |
-p |
Project to use |
--channel |
-c |
Channel to unpublish from |
--version |
-v |
Deployment version to unpublish |
--yes |
-y |
Skip confirmation prompt |
List Deployments
| Option | Abbr | Description | Default |
|---|---|---|---|
--workspace |
-w |
Workspace to query | |
--project |
-p |
Project to query | Current project |
--channel |
-c |
Filter by channel (shows what the channel serves) | |
--version |
-v |
Filter by version (shows its revisions) | |
--limit |
-l |
Maximum results | 10 |
Displays a table with columns: Version, Revision, Size (KB), Created By, Created At, Updated By, Updated At, Channels. The Channels column lists the channels currently serving each deployment — empty means the deployment is staged but not live anywhere.
Examples:
# List recent deployments for the current project
$ xc cloud deployment list
# What is production serving right now?
$ xc cloud deployment list -c production
# All revisions of a version
$ xc cloud deployment list -v 1.0.0
Delete Deployments
| Option | Abbr | Description |
|---|---|---|
--workspace |
-w |
Workspace to use |
--project |
-p |
Project to use |
--version |
-v |
Version to delete |
--revision |
-r |
Specific revision to delete |
--yes |
-y |
Skip confirmation prompt |
The deletion scope depends on which options are combined:
| Options | Effect |
|---|---|
--version + --revision |
Delete one specific revision |
--version only |
Delete all revisions of the version |
| neither | Delete all deployments in the project |
Deployments that are currently live cannot be deleted — the server refuses until you unpublish them from every channel that serves them. This protects live apps from losing their bundles.
The CLI prompts for confirmation before deleting.
Danger
Deployment deletion is permanent — the bundle bytes are removed from storage. Deleted revision numbers are never reused.