deploy.deployments.create

Start a deployment of an app

POST /deploy/api/apps/{id}/deploymentsIAM deploy:DeployAppChanges stateDestructive

imageRef deploys that image this once without changing the app. An image in this organization’s registry is resolved to a digest first. fromDeploymentId runs what that deployment ran; with trigger rollback it also restores the environment that deployment started with (restoreEnvironment, default true for a rollback, needs deploy:ManageEnv as well).

Request syntax

POST /deploy/api/apps/{id}/deployments
{
  "trigger": "enum",
  "gitCommitSha": "string",
  "imageRef": "string",
  "fromDeploymentId": "string",
  "reason": "string",
  "restoreEnvironment": "boolean"
}

Path parameters

  • idRequired

    string

    Constraints: uuid

Request body

  • triggerOptional

    enum

    rollback marks the deployment as a rollback and, with fromDeploymentId, restores that deployment’s environment by default

    One of: manual, rollback

    Default: "manual"

  • gitCommitShaOptional

    string

    Commit to build; omitted, the head of the app’s branch

    Constraints: 7-64 chars

  • imageRefOptional

    string

    Image to run for this deployment only; the app’s own image is not changed

    Constraints: 1-512 chars, /^[a-z0-9]([a-z0-9._-]*[a-z0-9])?(:[0-9]+)?(\/[a-z0-9]([a-z0-9._-]*[a-z0-9])?)*(:[A-Za-z0-9._-]+|@sha256:[a-f0-9]{64})?$/

  • fromDeploymentIdOptional

    string

    An earlier deployment of this app to run again: its image or pinned compose file, commit and release command

  • reasonOptional

    string

    Why, shown on the deployment timeline beside who started it

    Constraints: 1-500 chars

  • restoreEnvironmentOptional

    boolean

    With fromDeploymentId: also put back the environment that deployment started with; default true for a rollback, false otherwise

Response

201 with `data`: the new deployment (id, generation, trigger, status queued, gitCommitSha, imageRef, composeDigest, envSnapshot, reason, createdAt). envSnapshot is null unless the caller holds deploy:ManageEnv; the pinned compose file text is left out. Follow it with wait, events or build-log.

A JSON response is wrapped as { "success": true, "data": … }; the CLI prints the whole body with --json.

Fields of data

  • idAlways

    string

    Deployment id
  • appIdAlways

    string

    The app deployed
  • orgIdAlways

    string

    Organization the deployment belongs to
  • generationAlways

    number

    The app generation this deployment represents
  • triggerAlways

    one of push, manual, rollback

    What started it
  • gitCommitShaAlways

    string, may be null

    Commit built; null for an image or compose app
  • imageRefAlways

    string, may be null

    Image run, by digest once built; null for a compose deployment
  • composeDigestAlways

    string, may be null

    sha256 of the compose file pinned to it; null for other builders
  • composeImagePinsAlways

    map, may be null

    Compose: service name → image digest, for images whose signature was checked; null: none
  • envSnapshotAlways

    array of object, may be null

    The environment when it started (secrets by reference), what a rollback restores; null on older deployments and for a caller without deploy:ManageEnv
  • envSnapshot[].​keyAlways

    string

    Variable name
  • envSnapshot[].​valueKindAlways

    one of plain, secret

    plain or secret
  • envSnapshot[].​plainValueAlways

    string, may be null

    The value of a plain variable; null for a secret
  • envSnapshot[].​kmsSecretIdAlways

    string, may be null

    The Secret bound, for a secret; null for plain
  • statusAlways

    one of queued, building, pushing, deploying, live, failed, superseded

    queued, building, pushing, deploying, live, failed or superseded
  • releaseCommandAlways

    string, may be null

    Release command pinned when it started; null: none
  • releaseStatusAlways

    one of pending, running, succeeded, failed, skipped

    Where the release command stands; skipped when there is none
  • releaseExitCodeAlways

    number, may be null

    Exit code of the release command; null until it ran
  • buildLogRefAlways

    string, may be null

    Unused; always null
  • buildExitCodeAlways

    number, may be null

    Exit code the builder reported; null until it finished
  • errorMessageAlways

    string, may be null

    Why it failed; null unless failed
  • createdByAlways

    string, may be null

    IAM user who started it; null for a push or the platform
  • reasonAlways

    string, may be null

    Why it was started, as the starter said; null: none
  • statusHistoryAlways

    array of object

    Every status it passed through, oldest first
  • statusHistory[].​statusAlways

    string

    Status entered
  • statusHistory[].​atAlways

    string

    When
  • bundleKeyAlways

    string, may be null

    Pooled hosting: storage key of the uploaded bundle; null otherwise
  • bundleSha256Always

    string, may be null

    Pooled hosting: sha256 of the bundle
  • bundleBytesAlways

    number, may be null

    Pooled hosting: size of the bundle, in bytes
  • branchAlways

    string, may be null

    Pooled hosting: branch the commit was pushed to
  • previewAlways

    boolean

    Pooled hosting: a preview at its own URL rather than production
  • hostingSummaryAlways

    object, may be null

    Pooled hosting: what the bundle contains; null until read
  • hostingSummary.​kindAlways

    one of static, hybrid, fallback

    static: files only; hybrid: some routes need the server; fallback: all do
  • hostingSummary.​nextVersionAlways

    string, may be null

    Next.js version of the build; null if unknown
  • hostingSummary.​filesAlways

    number

    Number of files served without the server
  • hostingSummary.​nodeRoutesAlways

    array of object

    Routes the app’s server answers
  • hostingSummary.​nodeRoutes[].​pathAlways

    string

    Route
  • hostingSummary.​nodeRoutes[].​reasonAlways

    string

    Why it needs the server
  • createdAtAlways

    string

    When it was started
  • liveAtAlways

    string, may be null

    When it went live; null if it never did

Checked against the handlers: every route test validates their answers against this schema.

Errors

  • 400The request does not pass the schema above. The body is { "error": …, "issues": […] }, one issue per field.
  • 401No credentials, or an access key that is unknown, revoked or expired.
  • 403The caller's policies do not allow deploy:DeployApp on this resource. The body names the action and the resource, and the refusal is recorded in the audit log.
  • 404The resource does not exist in your organization.

Examples

The required parameters only, with example values. Replace id and the other placeholders with your own.

dcloud deploy deployments create id

Generated from the API description, the same one the API checks requests against and the CLI is built from. MCP tool: dcloud_deploy_deployments_create.