Change the environment's protection policy. Stricter policies need `env-write`; anything weaker needs an owner.

PUT

/api/v1/projects/{project}/environments/{environment}/policy

curl --request PUT \
  --url https://example.com/api/v1/projects/example/environments/example/policy \
  --header 'Content-Type: application/json' \
  --data '{ "requiredApprovals": 1, "deployRole": "developer", "approveRole": "admin", "approvalTtlSecs": 604800, "scan": { "mode": "block", "severity": "critical", "requireScan": true, "maxAgeSecs": 604800 } }'

Parameters

Path Parameters

project

required

string

Project name

environment

required

string

Environment short name

Request Body^required

Media typeapplication/json

object

requiredApprovals

required

Distinct approvers a deployment needs (0–5).

integer format: int32

Example

1

deployRole

required

The weakest role that may deploy: developer, admin or owner.

string

Example

developer

approveRole

required

The weakest role that may approve: admin or owner.

string

Example

admin

approvalTtlSecs

How long a deployment waits for approvals (300 s – 30 days).

integer format: int32

Example

604800

scan

One of:

null

null

object

The vulnerability gate; the current one is kept when omitted.

object

mode

required

off, warn or block.

string

Example

block

severity

required

Findings at or above this severity count: high or critical.

string

Example

critical

requireScan

An image without a fresh successful scan counts as a finding.

boolean

maxAgeSecs

A scan older than this no longer counts (1 hour – 90 days).

integer format: int32

Example

604800

Responses

200

Media typeapplication/json

object

revision

required

0 when the environment has no policy of its own yet.

integer format: int64

requiredApprovals

required

integer format: int32

deployRole

required

string

approveRole

required

string

approvalTtlSecs

required

integer format: int32

scan

required

What vulnerability findings a deployment may carry.

object

mode

required

off, warn or block.

string

severity

required

Findings at or above this severity count: high or critical.

string

requireScan

An image without a fresh successful scan counts as a finding.

boolean

maxAgeSecs

A scan older than this no longer counts (1 hour – 90 days).

integer format: int32

updatedBy

string | null

updatedAt

integer | null format: int64

Example

{
  "scan": {
    "mode": "block",
    "severity": "critical",
    "maxAgeSecs": 604800
  }
}

403

Weakening needs an owner; tokens cannot change policies

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"
}

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"
}