工件元数据的 REST API 终结点 - GitHub Enterprise Cloud Docs

可以使用这些端点来上传使用 GitHub Actions 构建的软件的存储和部署记录。记录显示在组织的linked artifacts page上。请参阅“关于关联的项目”。

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. The deployment name has to be uniqe within a cluster (i.e a combination of logical, physical environment and cluster) as it identifies unique deployment. Multiple requests for the same combination of logical, physical environment, cluster and deployment name will only create one record, successive request will update the existing record. This allows for a stable tracking of a deployment where the actual deployed artifact can change over time.

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)

“”Create an artifact deployment record 的参数

标头
名称, 类型, 说明
`accept` string Setting to `application/vnd.github+json` is recommended.

路径参数
名称, 类型, 说明
`org` string 必须 The organization name. The name is not case sensitive.

主体参数
名称, 类型, 说明
`name` string 必须 The name of the artifact.
`digest` string 必须 The hex encoded digest of the artifact.
`version` string The artifact version.
`status` string 必须 The status of the artifact. Can be either deployed or decommissioned. 可以是以下选项之一: `deployed`, `decommissioned`
`logical_environment` string 必须 The stage of the deployment.
`physical_environment` string The physical region of the deployment.
`cluster` string The deployment cluster.
`deployment_name` string 必须 The unique identifier for the deployment represented by the new record. To accommodate differing containers and namespaces within a cluster, the following format is recommended: {namespaceName}-{deploymentName}-{containerName}.
`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.
`return_records` boolean If true, the endpoint will return the created or updated record in the response body. 默认: `true`

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

Status code	说明
`200`	Artifact deployment record stored successfully.
`403`	Forbidden
`404`	Resource not found

Code samples for "Create an artifact deployment record"

If you access GitHub at GHE.com, replace api.github.com with your enterprise's dedicated subdomain at api.SUBDOMAIN.ghe.com.

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: 2026-03-10" \
  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. 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.

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)

“”Set cluster deployment records 的参数

标头
名称, 类型, 说明
`accept` string Setting to `application/vnd.github+json` is recommended.

路径参数
名称, 类型, 说明
`org` string 必须 The organization name. The name is not case sensitive.
`cluster` string 必须 The cluster name.

名称, 类型, 说明

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` 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. 默认: `deployed` 可以是以下选项之一: `deployed`, `decommissioned`
`deployment_name` string 必须 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.
`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`

return_records boolean

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

默认: true

HTTP response status codes for "Set cluster deployment records"

Status code	说明
`200`	Deployment records created or updated successfully.
`403`	Forbidden
`404`	Resource not found

Code samples for "Set cluster deployment records"

If you access GitHub at GHE.com, replace api.github.com with your enterprise's dedicated subdomain at api.SUBDOMAIN.ghe.com.

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: 2026-03-10" \
  https://api.github.com/orgs/ORG/artifacts/metadata/deployment-record/cluster/CLUSTER \
  -d '{"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":{"runtime-risk":"sensitive-data"}}]}'

Deployment records created or updated 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)

“”Create artifact metadata storage record 的参数

标头
名称, 类型, 说明
`accept` string Setting to `application/vnd.github+json` is recommended.

路径参数
名称, 类型, 说明
`org` string 必须 The organization name. The name is not case sensitive.

主体参数
名称, 类型, 说明
`name` string 必须 The name of the artifact.
`digest` string 必须 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 必须 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). 默认: `active` 可以是以下选项之一: `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.
`return_records` boolean If true, the endpoint will return the created record in the response body. 默认: `true`

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

Status code	说明
`200`	Artifact metadata storage record stored successfully.
`403`	Forbidden
`404`	Resource not found

Code samples for "Create artifact metadata storage record"

If you access GitHub at GHE.com, replace api.github.com with your enterprise's dedicated subdomain at api.SUBDOMAIN.ghe.com.

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: 2026-03-10" \
  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)

“”List artifact deployment records 的参数

标头
名称, 类型, 说明
`accept` string Setting to `application/vnd.github+json` is recommended.

路径参数
名称, 类型, 说明
`org` string 必须 The organization name. The name is not case sensitive.
`subject_digest` string 必须 The SHA256 digest of the artifact, in the form `sha256:HEX_DIGEST`.

HTTP response status codes for "List artifact deployment records"

Status code	说明
`200`	Successful response

Code samples for "List artifact deployment records"

If you access GitHub at GHE.com, replace api.github.com with your enterprise's dedicated subdomain at api.SUBDOMAIN.ghe.com.

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: 2026-03-10" \
  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)

“”List artifact storage records 的参数

标头
名称, 类型, 说明
`accept` string Setting to `application/vnd.github+json` is recommended.

路径参数
名称, 类型, 说明
`org` string 必须 The organization name. The name is not case sensitive.
`subject_digest` string 必须 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	说明
`200`	OK

Code samples for "List artifact storage records"

If you access GitHub at GHE.com, replace api.github.com with your enterprise's dedicated subdomain at api.SUBDOMAIN.ghe.com.

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: 2026-03-10" \
  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"
    }
  ]
}