attestations

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

Overview

Name	attestations
Type	Resource
Id	github.repos.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	owner, repo, subject_digest	per_page, before, after, predicate_type	List a collection of artifact attestations with a given subject digest that are associated with a repository. The authenticated user making the request must have read access to the repository. 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.
create_attestation	insert	owner, repo, bundle		Store an artifact attestation and associate it with a repository. The authenticated user must have write permission to the repository and, if using a fine-grained access token, the attestations:write permission is required. Artifact attestations are meant to be created using the attest action. For more information, see our guide on using artifact attestations to establish a build's provenance.

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
owner	string	The account owner of the repository. The name is not case sensitive.
repo	string	The name of the repository without the .git extension. 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.
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 a repository.

The authenticated user making the request must have read access to the repository. 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.repos.attestations
WHERE owner = '{{ owner }}' -- required
AND repo = '{{ repo }}' -- required
AND subject_digest = '{{ subject_digest }}' -- required
AND per_page = '{{ per_page }}'
AND before = '{{ before }}'
AND after = '{{ after }}'
AND predicate_type = '{{ predicate_type }}'
;

INSERT examples

create_attestation

Store an artifact attestation and associate it with a repository.

The authenticated user must have write permission to the repository and, if using a fine-grained access token, the attestations:write permission is required.

Artifact attestations are meant to be created using the attest action. For more information, see our guide on using artifact attestations to establish a build's provenance.

INSERT INTO github.repos.attestations (
bundle,
owner,
repo
)
SELECT 
'{{ bundle }}' /* required */,
'{{ owner }}',
'{{ repo }}'
RETURNING
id
;

Manifest

# Description fields are for documentation purposes
- name: attestations
props:
  - name: owner
    value: "{{ owner }}"
    description: Required parameter for the attestations resource.
  - name: repo
    value: "{{ repo }}"
    description: Required parameter for the attestations resource.
  - name: bundle
    description: |
      The attestation's Sigstore Bundle.
      Refer to the [Sigstore Bundle Specification](https://github.com/sigstore/protobuf-specs/blob/main/protos/sigstore_bundle.proto) for more information.
    value:
      mediaType: "{{ mediaType }}"
      verificationMaterial: "{{ verificationMaterial }}"
      dsseEnvelope: "{{ dsseEnvelope }}"