Accept a deployment of this app.

POST

/api/v1/projects/{project}/environments/{environment}/apps/{app}/deployments

curl --request POST \
  --url https://example.com/api/v1/projects/example/environments/example/apps/example/deployments \
  --header 'Content-Type: application/json' \
  --data '{ "image": "ghcr.io/acme/api@sha256:0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef", "release": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "config": "example", "reason": "deploy", "expected_generation": 1 }'

The release (from image, or an existing release), the configuration revision and the run are written in one transaction with the audit record and the message to the executors; then the call answers 202 with the run’s Location. Replaying the request with the same Idempotency-Key returns the first run.

Parameters

Path Parameters

project

required

string

Project name

environment

required

string

Environment short name

app

required

string

App name

Header Parameters

Idempotency-Key

string | null

Replays of the same request return the first run

Request Body^required

Media typeapplication/json

object

image

Image by digest: registry/repository@sha256:…. Give either image or release.

string | null

Example

ghcr.io/acme/api@sha256:0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef

release

An existing release of this app: a rollback or a redeploy.

string | null format: uuid

config

The app configuration: the app spec without its image. Omitted, the app’s latest configuration is used.

object | null

reason

Why a run exists.

string

Allowed values: deploy rollback promotion

expected_generation

required

The target generation the caller last saw. A deploy never silently replaces a newer one: a stale value is refused with 409.

integer format: int64

Responses

202

Accepted: poll the Location

Media typeapplication/json

A deployment run and where it stands.

object

run

required

string format: uuid

operation

required

string format: uuid

generation

required

The target generation this run owns.

integer format: int64

phase

required

planned, awaitingApproval, pendingDelivery, acceptedByCluster, applying, succeeded, failed, superseded, cancelled, …

string

approvals_required

Distinct approvals the environment’s policy requires before delivery.

integer format: int32

approval_expires_at

When a run waiting for approval is cancelled (Unix milliseconds).

integer | null format: int64

plan_hash

The hash approvers confirm (hex), when approvals are required.

string | null

warnings

What admission could not check, e.g. that the pods will be scheduled.

Array<string>

Example^generated

{
  "run": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0",
  "operation": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0",
  "generation": 1,
  "phase": "example",
  "approvals_required": 1,
  "approval_expires_at": 1,
  "plan_hash": "example",
  "warnings": [
    "example"
  ]
}

403

Media typeapplication/json

Problem Details body.

object

code

required

Stable machine-readable code, e.g. forbidden.

string

title

required

Short human readable title.

string

status

required

HTTP status.

integer format: int32

detail

Details, if safe to expose.

string | null

Example

{
  "code": "forbidden"
}

404

Media typeapplication/json

Problem Details body.

object

code

required

Stable machine-readable code, e.g. forbidden.

string

title

required

Short human readable title.

string

status

required

HTTP status.

integer format: int32

detail

Details, if safe to expose.

string | null

Example

{
  "code": "forbidden"
}

409

A stale expected generation, or an Idempotency-Key used for another request

Media typeapplication/json

Problem Details body.

object

code

required

Stable machine-readable code, e.g. forbidden.

string

title

required

Short human readable title.

string

status

required

HTTP status.

integer format: int32

detail

Details, if safe to expose.

string | null

Example

{
  "code": "forbidden"
}

422

Media typeapplication/json

Problem Details body.

object

code

required

Stable machine-readable code, e.g. forbidden.

string

title

required

Short human readable title.

string

status

required

HTTP status.

integer format: int32

detail

Details, if safe to expose.

string | null

Example

{
  "code": "forbidden"
}