Skip to content
forgit api docs

Set cluster deployment records

POST
/orgs/{org}/artifacts/metadata/deployment-record/cluster/{cluster}

Set deployment records for a given cluster. If proposed records in the ‘deployments’ field have identical ‘cluster’, ‘logical_environment’, ‘physical_environment’, and ‘deployment_name’ values as existing records, the existing records will be updated. If no existing records match, new records will be created. Note: Artifacts are uniquely identified by the combination of their repository and digest fields. If two entries in the deployments array resolve to the same repository and have identical digest fields but differing name and version fields, the endpoint will use the artifact name and version from the record processed first, since a single artifact (identified by repository and digest) can only have one name and version.

API method documentation

Parameters

Section titled “ Parameters ”

Path Parameters

Section titled “ Path Parameters ”
org
required
string

The organization name. The name is not case sensitive.

cluster
required
string
>= 1 characters <= 128 characters /^[a-zA-Z0-9._-]+$/

The cluster name.

Request Body required

Section titled “ Request Body required ”
Media type application/json
object
logical_environment
required

The stage of the deployment.

string
>= 1 characters <= 128 characters
physical_environment

The physical region of the deployment.

string
<= 128 characters
deployments
required

The list of deployments to record.

Array<object>
<= 1000 items
object
name
required

The name of the artifact.

string
>= 1 characters <= 256 characters
digest
required

The hex encoded digest of the artifact.

string
>= 71 characters <= 71 characters /^sha256:[a-f0-9]{64}$/
version

The artifact version.

string
<= 100 characters
status

The deployment status of the artifact.

string
default: deployed
Allowed values: deployed decommissioned
deployment_name
required

The unique identifier for the deployment represented by the new record. To accommodate differing containers and namespaces within a record set, the following format is recommended: {namespaceName}-{deploymentName}-{containerName}. The deployment_name must be unique across all entries in the deployments array.

string
>= 1 characters <= 256 characters
github_repository

The name of the GitHub repository associated with the artifact. This should be used when there are no provenance attestations available for the artifact. The repository must belong to the organization specified in the path parameter.

If a provenance attestation is available for the artifact, the API will use the repository information from the attestation instead of this parameter.

string
<= 100 characters /^[A-Za-z0-9.\-_]+$/
tags

Key-value pairs to tag the deployment record.

object
key
additional properties
string
runtime_risks

A list of runtime risks associated with the deployment.

Array<string>
<= 4 items unique items
Allowed values: critical-resource internet-exposed lateral-movement sensitive-data
partial_success

When enabled, deployments associated with repositories the actor can write to are processed while deployments associated with repositories that cannot be resolved or written to by the actor are skipped and reported in the errors array. When false (the default), the endpoint returns an error if any targeted repository cannot be resolved, the actor lacks write access, or no matching attestation can be found.

boolean
return_records

If true, the endpoint will return the set records in the response body

boolean
default: true
Examples
Example default 
{
  "logical_environment": "prod",
  "physical_environment": "pacific-east",
  "deployments": [
    {
      "name": "awesome-image",
      "digest": "sha256:1bb1e949e55dcefc6353e7b36c8897d2a107d8e8dca49d4e3c0ea8493fc0bc72",
      "version": "2.1.0",
      "status": "deployed",
      "deployment_name": "deployment-pod",
      "tags": {
        "owning-team": "platform"
      },
      "runtime_risks": [
        "sensitive-data"
      ]
    }
  ]
}

Responses

Section titled “ Responses ”

200

Section titled “ 200 ”

Deployment records created or updated successfully.

Media type application/json
object
total_count
required

The number of deployment records created

integer
deployment_records
Array<object>
Artifact Deployment Record

Artifact Metadata Deployment Record

object
id
integer
digest
string
logical_environment
string
physical_environment
string
cluster
string
deployment_name
string
tags
object
key
additional properties
string
runtime_risks

A list of runtime risks associated with the deployment.

Array<string>
<= 4 items unique items
Allowed values: critical-resource internet-exposed lateral-movement sensitive-data
created_at
string
updated_at
string
attestation_id

The ID of the provenance attestation associated with the deployment record.

integer
nullable
Examples
Example default 
{
  "total_count": 1,
  "deployment_records": [
    {
      "id": 123,
      "digest": "sha256:1bb1e949e55dcefc6353e7b36c8897d2a107d8e8dca49d4e3c0ea8493fc0bc72",
      "logical_environment": "prod",
      "physical_environment": "pacific-east",
      "cluster": "moda-1",
      "deployment_name": "prod-deployment",
      "tags": {
        "data": "sensitive"
      },
      "created": "2011-01-26T19:14:43Z",
      "updated_at": "2011-01-26T19:14:43Z",
      "attestation_id": 456
    }
  ]
}

207

Section titled “ 207 ”

This response format is only returned when partial_success is set to true in the request body. Successfully processed deployments are included in the deployment_records field. Records that could not be processed and were skipped because of unresolvable repositories, missing actor permissions, or lack of a matching attestation are included in the errors field.

Media type application/json
object
total_count
required

The number of deployment records created or updated.

integer
deployment_records
Array<object>
Artifact Deployment Record

Artifact Metadata Deployment Record

object
id
integer
digest
string
logical_environment
string
physical_environment
string
cluster
string
deployment_name
string
tags
object
key
additional properties
string
runtime_risks

A list of runtime risks associated with the deployment.

Array<string>
<= 4 items unique items
Allowed values: critical-resource internet-exposed lateral-movement sensitive-data
created_at
string
updated_at
string
attestation_id

The ID of the provenance attestation associated with the deployment record.

integer
nullable
errors

A list of errors for deployments that could not be processed.

Array<object>
object
cause

The reason the deployment failed processing.

string
Allowed values: unauthorized not_found
deployment

The deployment payload that could not be processed.

object
name

The name of the artifact.

string
digest

The digest of the artifact.

string
deployment_name

The name of the deployment that failed processing.

string
version

The version of the deployment.

string
nullable
status

The deployment status.

string
github_repository

The repository associated with the deployment.

string
nullable
tags

Custom metadata tags for the deployment.

object
key
additional properties
string
runtime_risks

Runtime risk classifications for the deployment.

Array<string>
Examples
Example partial_success 
{
  "total_count": 1,
  "deployment_records": [
    {
      "id": 42,
      "digest": "sha256:1bb1e949e55dcefc6353e7b36c8897d2a107d8e8dca49d4e3c0ea8493fc0bc72",
      "logical_environment": "prod",
      "physical_environment": "us-east-1a",
      "cluster": "production-cluster",
      "deployment_name": "deployment-pod",
      "tags": {
        "owning-team": "platform"
      },
      "runtime_risks": [
        "sensitive-data"
      ],
      "created_at": "2024-01-01T12:00:00Z",
      "updated_at": "2024-01-01T12:30:00Z",
      "attestation_id": 777
    }
  ],
  "errors": [
    {
      "cause": "unauthorized",
      "deployment": {
        "name": "my-image",
        "digest": "sha256:5aa19f9a13f67a644f6d8528e2eb5cf64431e236df5dbbd44ff9b9e3f6fc6cb2",
        "deployment_name": "restricted-deployment",
        "version": "2.1.1",
        "status": "deployed",
        "github_repository": "private-repo",
        "tags": {
          "owning-team": "platform"
        },
        "runtime_risks": [
          "sensitive-data"
        ]
      }
    }
  ]
}

403

Section titled “ 403 ”

Forbidden

Media type application/json
Basic Error

Basic Error

object
message
string
documentation_url
string
url
string
status
string
Examples
Example insufficient_repo_permissions 
{
  "message": {
    "cause": "artifact metadata write permission required on one or more repositories",
    "repositories": [
      123,
      345
    ]
  }
}

404

Section titled “ 404 ”

Resource not found

Media type application/json
Basic Error

Basic Error

object
message
string
documentation_url
string
url
string
status
string
Examples
Example not_found 
{
  "message": {
    "cause": "One or more repositories do not exist",
    "repositories": [
      "repoA",
      "repoB"
    ]
  }
}