attestations

Creates, updates, deletes, gets or lists an attestations resource.

Overview

Name	attestations
Type	Resource
Id	github.orgs.attestations

Fields

The following fields are returned by SELECT queries:

list_attestations

Response

Name	Datatype	Description
repository_id	integer
bundle	object	The attestation's Sigstore Bundle. Refer to the Sigstore Bundle Specification for more information.
bundle_url	string
initiator	string

Methods

The following methods are available for this resource:

Name	Accessible by	Required Params	Optional Params	Description
list_attestations	select	org, subject_digest	per_page, before, after, predicate_type	List a collection of artifact attestations with a given subject digest that are associated with repositories owned by an organization. The collection of attestations 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 attestations:read permission is required. Please note: in order to offer meaningful security benefits, an attestation's signature and timestamps must be cryptographically verified, and the identity of the attestation signer must be validated. Attestations can be verified using the GitHub CLI attestation verify command. For more information, see our guide on how to use artifact attestations to establish a build's provenance.
delete_attestations_by_subject_digest	delete	org, subject_digest		Delete an artifact attestation by subject digest.
delete_attestations_by_id	delete	org, attestation_id		Delete an artifact attestation by unique ID that is associated with a repository owned by an org.
list_attestations_bulk	exec	org, subject_digests	per_page, before, after	List a collection of artifact attestations associated with any entry in a list of subject digests owned by an organization. The collection of attestations 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 attestations:read permission is required. Please note: in order to offer meaningful security benefits, an attestation's signature and timestamps must be cryptographically verified, and the identity of the attestation signer must be validated. Attestations can be verified using the GitHub CLI attestation verify command. For more information, see our guide on how to use artifact attestations to establish a build's provenance.
delete_attestations_bulk	exec	org, subject_digests, attestation_ids		Delete artifact attestations in bulk by either subject digests or unique ID.

Parameters

Parameters can be passed in the WHERE clause of a query. Check the Methods section to see which parameters are required or optional for each operation.

Name	Datatype	Description
attestation_id	integer	Attestation ID
org	string	The organization name. The name is not case sensitive.
subject_digest	string	Subject Digest
after	string	A cursor, as given in the Link header. If specified, the query only searches for results after this cursor. For more information, see "Using pagination in the REST API."
before	string	A cursor, as given in the Link header. If specified, the query only searches for results before this cursor. For more information, see "Using pagination in the REST API."
per_page	integer	The number of results per page (max 100). For more information, see "Using pagination in the REST API."
predicate_type	string	Optional filter for fetching attestations with a given predicate type. This option accepts provenance, sbom, release, or freeform text for custom predicate types.

SELECT examples

list_attestations

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

The collection of attestations 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 attestations:read permission is required.

Please note: in order to offer meaningful security benefits, an attestation's signature and timestamps must be cryptographically verified, and the identity of the attestation signer must be validated. Attestations can be verified using the GitHub CLI attestation verify command. For more information, see our guide on how to use artifact attestations to establish a build's provenance.

SELECT
repository_id,
bundle,
bundle_url,
initiator
FROM github.orgs.attestations
WHERE org = '{{ org }}' -- required
AND subject_digest = '{{ subject_digest }}' -- required
AND per_page = '{{ per_page }}'
AND before = '{{ before }}'
AND after = '{{ after }}'
AND predicate_type = '{{ predicate_type }}'
;

DELETE examples

delete_attestations_by_subject_digest

Delete an artifact attestation by subject digest.

DELETE FROM github.orgs.attestations
WHERE org = '{{ org }}' --required
AND subject_digest = '{{ subject_digest }}' --required
;

delete_attestations_by_id

Delete an artifact attestation by unique ID that is associated with a repository owned by an org.

DELETE FROM github.orgs.attestations
WHERE org = '{{ org }}' --required
AND attestation_id = '{{ attestation_id }}' --required
;

Lifecycle Methods

list_attestations_bulk

List a collection of artifact attestations associated with any entry in a list of subject digests owned by an organization.

The collection of attestations 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 attestations:read permission is required.

Please note: in order to offer meaningful security benefits, an attestation's signature and timestamps must be cryptographically verified, and the identity of the attestation signer must be validated. Attestations can be verified using the GitHub CLI attestation verify command. For more information, see our guide on how to use artifact attestations to establish a build's provenance.

EXEC github.orgs.attestations.list_attestations_bulk 
@org='{{ org }}' --required, 
@per_page='{{ per_page }}', 
@before='{{ before }}', 
@after='{{ after }}' 
@@json=
'{
"subject_digests": "{{ subject_digests }}", 
"predicate_type": "{{ predicate_type }}"
}'
;

delete_attestations_bulk

Delete artifact attestations in bulk by either subject digests or unique ID.

EXEC github.orgs.attestations.delete_attestations_bulk 
@org='{{ org }}' --required 
@@json=
'{
"subject_digests": "{{ subject_digests }}", 
"attestation_ids": "{{ attestation_ids }}"
}'
;