suites

Creates, updates, deletes, gets or lists a suites resource.

Overview

Name	suites
Type	Resource
Id	github.checks.suites

Fields

The following fields are returned by SELECT queries:

get_suite

Response

Name	Datatype	Description
id	integer (int64)
node_id	string	(example: MDEwOkNoZWNrU3VpdGU1)
after	string	(example: d6fde92930d4715a2b49857d24b940956b26d2d3)
app	object	GitHub apps are a new way to extend GitHub. They can be installed directly on organizations and user accounts and granted access to specific repositories. They come with granular permissions and built-in webhooks. GitHub apps are first class actors within GitHub. (title: GitHub app)
before	string	(example: 146e867f55c26428e5f9fade55a9bbf5e95a7912)
check_runs_url	string
conclusion	string	(success, failure, neutral, cancelled, skipped, timed_out, action_required, startup_failure, stale, ) (example: neutral)
created_at	string (date-time)
head_branch	string	(example: master)
head_commit	object	A commit. (title: Simple Commit)
head_sha	string	The SHA of the head commit that is being checked. (example: 009b8a3a9ccbb128af87f9b1c0f4c62e8a304f6d)
latest_check_runs_count	integer
pull_requests	array
repository	object	Minimal Repository (title: Minimal Repository)
rerequestable	boolean
runs_rerequestable	boolean
status	string	The phase of the lifecycle that the check suite is currently in. Statuses of waiting, requested, and pending are reserved for GitHub Actions check suites. (queued, in_progress, completed, waiting, requested, pending) (example: completed)
updated_at	string (date-time)
url	string	(example: https://api.github.com/repos/github/hello-world/check-suites/5)

list_suites_for_ref

Response

Name	Datatype	Description
check_suites	array
total_count	integer

Methods

The following methods are available for this resource:

Name	Accessible by	Required Params	Optional Params	Description
get_suite	select	owner, repo, check_suite_id		Gets a single check suite using its id. > [!NOTE] > The Checks API only looks for pushes in the repository where the check suite or check run were created. Pushes to a branch in a forked repository are not detected and return an empty pull_requests array and a null value for head_branch. OAuth app tokens and personal access tokens (classic) need the repo scope to use this endpoint on a private repository.
list_suites_for_ref	select	owner, repo, ref	app_id, check_name, per_page, page	Lists check suites for a commit ref. The ref can be a SHA, branch name, or a tag name. > [!NOTE] > The endpoints to manage checks only look for pushes in the repository where the check suite or check run were created. Pushes to a branch in a forked repository are not detected and return an empty pull_requests array and a null value for head_branch. OAuth app tokens and personal access tokens (classic) need the repo scope to use this endpoint on a private repository.
create_suite	insert	owner, repo, head_sha		Creates a check suite manually. By default, check suites are automatically created when you create a check run. You only need to use this endpoint for manually creating check suites when you've disabled automatic creation using "Update repository preferences for check suites". > [!NOTE] > The Checks API only looks for pushes in the repository where the check suite or check run were created. Pushes to a branch in a forked repository are not detected and return an empty pull_requests array and a null value for head_branch. OAuth apps and personal access tokens (classic) cannot use this endpoint.
set_suites_preferences	update	owner, repo		Changes the default automatic flow when creating check suites. By default, a check suite is automatically created each time code is pushed to a repository. When you disable the automatic creation of check suites, you can manually Create a check suite. You must have admin permissions in the repository to set preferences for check suites.
rerequest_suite	exec	owner, repo, check_suite_id		Triggers GitHub to rerequest an existing check suite, without pushing new code to a repository. This endpoint will trigger the check_suite webhook event with the action rerequested. When a check suite is rerequested, its status is reset to queued and the conclusion is cleared.

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
check_suite_id	integer	The unique identifier of the check suite.
owner	string	The account owner of the repository. The name is not case sensitive.
ref	string	The commit reference. Can be a commit SHA, branch name (heads/BRANCH_NAME), or tag name (tags/TAG_NAME). For more information, see "Git References" in the Git documentation.
repo	string	The name of the repository without the .git extension. The name is not case sensitive.
app_id	integer	Filters check suites by GitHub App id. (example: 1)
check_name	string	Returns check runs with the specified name.
page	integer	The page number of the results to fetch. 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."

SELECT examples

get_suite

Gets a single check suite using its id.

> [!NOTE]
> The Checks API only looks for pushes in the repository where the check suite or check run were created. Pushes to a branch in a forked repository are not detected and return an empty pull_requests array and a null value for head_branch.

OAuth app tokens and personal access tokens (classic) need the repo scope to use this endpoint on a private repository.

SELECT
id,
node_id,
after,
app,
before,
check_runs_url,
conclusion,
created_at,
head_branch,
head_commit,
head_sha,
latest_check_runs_count,
pull_requests,
repository,
rerequestable,
runs_rerequestable,
status,
updated_at,
url
FROM github.checks.suites
WHERE owner = '{{ owner }}' -- required
AND repo = '{{ repo }}' -- required
AND check_suite_id = '{{ check_suite_id }}' -- required
;

list_suites_for_ref

Lists check suites for a commit ref. The ref can be a SHA, branch name, or a tag name.

> [!NOTE]
> The endpoints to manage checks only look for pushes in the repository where the check suite or check run were created. Pushes to a branch in a forked repository are not detected and return an empty pull_requests array and a null value for head_branch.

OAuth app tokens and personal access tokens (classic) need the repo scope to use this endpoint on a private repository.

SELECT
check_suites,
total_count
FROM github.checks.suites
WHERE owner = '{{ owner }}' -- required
AND repo = '{{ repo }}' -- required
AND ref = '{{ ref }}' -- required
AND app_id = '{{ app_id }}'
AND check_name = '{{ check_name }}'
AND per_page = '{{ per_page }}'
AND page = '{{ page }}'
;

INSERT examples

create_suite

Creates a check suite manually. By default, check suites are automatically created when you create a check run. You only need to use this endpoint for manually creating check suites when you've disabled automatic creation using "Update repository preferences for check suites".

> [!NOTE]
> The Checks API only looks for pushes in the repository where the check suite or check run were created. Pushes to a branch in a forked repository are not detected and return an empty pull_requests array and a null value for head_branch.

OAuth apps and personal access tokens (classic) cannot use this endpoint.

INSERT INTO github.checks.suites (
head_sha,
owner,
repo
)
SELECT 
'{{ head_sha }}' /* required */,
'{{ owner }}',
'{{ repo }}'
RETURNING
id,
node_id,
after,
app,
before,
check_runs_url,
conclusion,
created_at,
head_branch,
head_commit,
head_sha,
latest_check_runs_count,
pull_requests,
repository,
rerequestable,
runs_rerequestable,
status,
updated_at,
url
;

Manifest

# Description fields are for documentation purposes
- name: suites
props:
  - name: owner
    value: "{{ owner }}"
    description: Required parameter for the suites resource.
  - name: repo
    value: "{{ repo }}"
    description: Required parameter for the suites resource.
  - name: head_sha
    value: "{{ head_sha }}"
    description: |
      The sha of the head commit.

UPDATE examples

set_suites_preferences

Changes the default automatic flow when creating check suites. By default, a check suite is automatically created each time code is pushed to a repository. When you disable the automatic creation of check suites, you can manually Create a check suite.
You must have admin permissions in the repository to set preferences for check suites.

UPDATE github.checks.suites
SET 
auto_trigger_checks = '{{ auto_trigger_checks }}'
WHERE 
owner = '{{ owner }}' --required
AND repo = '{{ repo }}' --required
RETURNING
preferences,
repository;

Lifecycle Methods

rerequest_suite

Triggers GitHub to rerequest an existing check suite, without pushing new code to a repository. This endpoint will trigger the check_suite webhook event with the action rerequested. When a check suite is rerequested, its status is reset to queued and the conclusion is cleared.

EXEC github.checks.suites.rerequest_suite 
@owner='{{ owner }}' --required, 
@repo='{{ repo }}' --required, 
@check_suite_id='{{ check_suite_id }}' --required
;