REST API endpoints for artifact metadata

When you view Dependabot or code scanning alerts for an organization, you can use artifact metadata to filter and prioritize alerts, see Prioritizing Dependabot and code scanning alerts using production context.

Create an artifact deployment record

Create or update deployment records for an artifact associated with an organization. This endpoint allows you to record information about a specific artifact, such as its name, digest, environments, cluster, and deployment.

Fine-grained access tokens for "Create an artifact deployment record"

This endpoint works with the following fine-grained token types:

The fine-grained token must have at least one of the following permission sets:

"Contents" repository permissions (write)
"Artifact metadata" repository permissions (write)

Parameters for "Create an artifact deployment record"

Headers
Name, Type, Description
`accept` string Setting to `application/vnd.github+json` is recommended.

Path parameters
Name, Type, Description
`org` string Required The organization name. The name is not case sensitive.

Body parameters
Name, Type, Description
`name` string Required The name of the artifact.
`digest` string Required The hex encoded digest of the artifact.
`version` string The artifact version.
`status` string Required The status of the artifact. Can be either deployed or decommissioned. Can be one of: `deployed`, `decommissioned`
`logical_environment` string Required The stage of the deployment.
`physical_environment` string The physical region of the deployment.
`cluster` string The deployment cluster.
`deployment_name` string Required The name of the deployment.
`tags` object The tags associated with the deployment.
`runtime_risks` array of strings A list of runtime risks associated with the deployment. Supported values are: `critical-resource`, `internet-exposed`, `lateral-movement`, `sensitive-data`
`github_repository` string 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.

HTTP response status codes for "Create an artifact deployment record"

Status code	Description
`200`	Artifact deployment record stored successfully.

Code samples for "Create an artifact deployment record"

Request example

post/orgs/{org}/artifacts/metadata/deployment-record

curl -L \
  -X POST \
  -H "Accept: application/vnd.github+json" \
  -H "Authorization: Bearer <YOUR-TOKEN>" \
  -H "X-GitHub-Api-Version: 2022-11-28" \
  https://api.github.com/orgs/ORG/artifacts/metadata/deployment-record \
  -d '{"name":"awesome-image","digest":"sha256:1bb1e949e55dcefc6353e7b36c8897d2a107d8e8dca49d4e3c0ea8493fc0bc72","status":"deployed","logical_environment":"prod","physical_environment":"pacific-east","cluster":"moda-1","deployment_name":"deployment-pod","tags":{"data-access":"sensitive"}}'

Artifact deployment record stored successfully.

Status: 200

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

Set cluster deployment records

Set deployment records for a given cluster.

Fine-grained access tokens for "Set cluster deployment records"

This endpoint works with the following fine-grained token types:

The fine-grained token must have at least one of the following permission sets:

"Contents" repository permissions (write)
"Artifact metadata" repository permissions (write)

Parameters for "Set cluster deployment records"

Headers
Name, Type, Description
`accept` string Setting to `application/vnd.github+json` is recommended.

Path parameters
Name, Type, Description
`org` string Required The organization name. The name is not case sensitive.
`cluster` string Required The cluster name.

Name, Type, Description

logical_environment string

The stage of the deployment.

physical_environment string

The physical region of the deployment.

deployments array of objects

The list of deployments to record.

Properties of deployments

Name, Type, Description
`name` string The name of the artifact.
`digest` string The hex encoded digest of the artifact.
`version` string The artifact version.
`status` string The deployment status of the artifact. Can be one of: `deployed`, `decommissioned`
`deployment_name` string The name of the deployment.
`github_repository` string 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.
`tags` object Key-value pairs to tag the deployment record.
`runtime_risks` array of strings A list of runtime risks associated with the deployment. Supported values are: `critical-resource`, `internet-exposed`, `lateral-movement`, `sensitive-data`

HTTP response status codes for "Set cluster deployment records"

Status code	Description
`200`	Artifact deployment record stored successfully.

Code samples for "Set cluster deployment records"

Request example

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

curl -L \
  -X POST \
  -H "Accept: application/vnd.github+json" \
  -H "Authorization: Bearer <YOUR-TOKEN>" \
  -H "X-GitHub-Api-Version: 2022-11-28" \
  https://api.github.com/orgs/ORG/artifacts/metadata/deployment-record/cluster/CLUSTER \
  -d '{"name":"awesome-image","digest":"sha256:1bb1e949e55dcefc6353e7b36c8897d2a107d8e8dca49d4e3c0ea8493fc0bc72","version":"2.1.0","status":"deployed","logical_environment":"prod","physical_environment":"pacific-east","cluster":"moda-1","deployment_name":"deployment-pod","tags":{"runtime-risk":"sensitive-data"}}'

Artifact deployment record stored successfully.

Status: 200

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

Create artifact metadata storage record

Create metadata storage records for artifacts associated with an organization. This endpoint will create a new artifact storage record on behalf of any artifact matching the provided digest and associated with a repository owned by the organization.

Fine-grained access tokens for "Create artifact metadata storage record"

This endpoint works with the following fine-grained token types:

The fine-grained token must have at least one of the following permission sets:

"Contents" repository permissions (write)
"Artifact metadata" repository permissions (write)

Parameters for "Create artifact metadata storage record"

Headers
Name, Type, Description
`accept` string Setting to `application/vnd.github+json` is recommended.

Path parameters
Name, Type, Description
`org` string Required The organization name. The name is not case sensitive.

Body parameters
Name, Type, Description
`name` string Required The name of the artifact.
`digest` string Required The digest of the artifact (algorithm:hex-encoded-digest).
`version` string The artifact version.
`artifact_url` string The URL where the artifact is stored.
`path` string The path of the artifact.
`registry_url` string Required The base URL of the artifact registry.
`repository` string The repository name within the registry.
`status` string The status of the artifact (e.g., active, inactive). Default: `active` Can be one of: `active`, `eol`, `deleted`
`github_repository` string 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.

HTTP response status codes for "Create artifact metadata storage record"

Status code	Description
`200`	Artifact metadata storage record stored successfully.

Code samples for "Create artifact metadata storage record"

Request example

post/orgs/{org}/artifacts/metadata/storage-record

curl -L \
  -X POST \
  -H "Accept: application/vnd.github+json" \
  -H "Authorization: Bearer <YOUR-TOKEN>" \
  -H "X-GitHub-Api-Version: 2022-11-28" \
  https://api.github.com/orgs/ORG/artifacts/metadata/storage-record \
  -d '{"name":"libfoo","version":"1.2.3","digest":"sha256:1bb1e949e55dcefc6353e7b36c8897d2a107d8e8dca49d4e3c0ea8493fc0bc72","artifact_url":"https://reg.example.com/artifactory/bar/libfoo-1.2.3","registry_url":"https://reg.example.com/artifactory/","repository":"bar","status":"active"}'

Artifact metadata storage record stored successfully.

Status: 200

{
  "total_count": 1,
  "storage_records": [
    {
      "name": "libfoo",
      "digest": "sha256:1bb1e949e55dcefc6353e7b36c8897d2a107d8e8dca49d4e3c0ea8493fc0bc72",
      "artifact_url": "https://reg.example.com/artifactory/bar/libfoo-1.2.3",
      "registry_url": "https://reg.example.com/artifactory/",
      "repository": "bar",
      "status": "active",
      "created_at": "2023-10-01T12:00:00Z",
      "updated_at": "2023-10-01T12:00:00Z"
    }
  ]
}

List artifact deployment records

List deployment records for an artifact metadata associated with an organization.

Fine-grained access tokens for "List artifact deployment records"

This endpoint works with the following fine-grained token types:

The fine-grained token must have at least one of the following permission sets:

"Contents" repository permissions (read)
"Artifact metadata" repository permissions (read)

Parameters for "List artifact deployment records"

Headers
Name, Type, Description
`accept` string Setting to `application/vnd.github+json` is recommended.

Path parameters
Name, Type, Description
`org` string Required The organization name. The name is not case sensitive.
`subject_digest` string Required The SHA256 digest of the artifact, in the form `sha256:HEX_DIGEST`.

HTTP response status codes for "List artifact deployment records"

Status code	Description
`200`	Successful response

Code samples for "List artifact deployment records"

Request example

get/orgs/{org}/artifacts/{subject_digest}/metadata/deployment-records

curl -L \
  -H "Accept: application/vnd.github+json" \
  -H "Authorization: Bearer <YOUR-TOKEN>" \
  -H "X-GitHub-Api-Version: 2022-11-28" \
  https://api.github.com/orgs/ORG/artifacts/SUBJECT_DIGEST/metadata/deployment-records

Successful response

Status: 200

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

List artifact storage records

List a collection of artifact storage records with a given subject digest that are associated with repositories owned by an organization.

The collection of storage records returned by this endpoint is filtered according to the authenticated user's permissions; if the authenticated user cannot read a repository, the attestations associated with that repository will not be included in the response. In addition, when using a fine-grained access token the content:read permission is required.

Fine-grained access tokens for "List artifact storage records"

This endpoint works with the following fine-grained token types:

The fine-grained token must have at least one of the following permission sets:

"Contents" repository permissions (read)
"Artifact metadata" repository permissions (read)

Parameters for "List artifact storage records"

Headers
Name, Type, Description
`accept` string Setting to `application/vnd.github+json` is recommended.

Path parameters
Name, Type, Description
`org` string Required The organization name. The name is not case sensitive.
`subject_digest` string Required The parameter should be set to the attestation's subject's SHA256 digest, in the form `sha256:HEX_DIGEST`.

HTTP response status codes for "List artifact storage records"

Status code	Description
`200`	OK

Code samples for "List artifact storage records"

Request example

get/orgs/{org}/artifacts/{subject_digest}/metadata/storage-records

curl -L \
  -H "Accept: application/vnd.github+json" \
  -H "Authorization: Bearer <YOUR-TOKEN>" \
  -H "X-GitHub-Api-Version: 2022-11-28" \
  https://api.github.com/orgs/ORG/artifacts/SUBJECT_DIGEST/metadata/storage-records

Response

Status: 200

{
  "storage_records": [
    {
      "name": "libfoo-1.2.3",
      "digest": "sha256:1bb1e949e55dcefc6353e7b36c8897d2a107d8e8dca49d4e3c0ea8493fc0bc72",
      "artifact_url": "https://reg.example.com/artifactory/bar/libfoo-1.2.3",
      "registry_url": "https://reg.example.com/artifactory/",
      "repository": "bar",
      "status": "active",
      "created_at": "2023-10-01T12:00:00Z",
      "updated_at": "2023-10-01T12:00:00Z"
    }
  ]
}