runs

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

Overview

Name	runs
Type	Resource
Id	github.checks.runs

Fields

The following fields are returned by SELECT queries:

get

Response

Name	Datatype	Description
id	integer (int64)	The id of the check.
name	string	The name of the check. (example: test-coverage)
external_id	string	(example: 42)
node_id	string	(example: MDg6Q2hlY2tSdW40)
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)
check_suite	object
completed_at	string (date-time)	(example: 2018-05-04T01:14:52Z)
conclusion	string	(success, failure, neutral, cancelled, skipped, timed_out, action_required) (example: neutral)
deployment	object	A deployment created as the result of an Actions check run from a workflow that references an environment (title: Deployment)
details_url	string	(example: https://example.com)
head_sha	string	The SHA of the commit that is being checked. (example: 009b8a3a9ccbb128af87f9b1c0f4c62e8a304f6d)
html_url	string	(example: https://github.com/github/hello-world/runs/4)
output	object
pull_requests	array	Pull requests that are open with a head_sha or head_branch that matches the check. The returned pull requests do not necessarily indicate pull requests that triggered the check.
started_at	string (date-time)	(example: 2018-05-04T01:14:52Z)
status	string	The phase of the lifecycle that the check is currently in. Statuses of waiting, requested, and pending are reserved for GitHub Actions check runs. (queued, in_progress, completed, waiting, requested, pending) (example: queued)
url	string	(example: https://api.github.com/repos/github/hello-world/check-runs/4)

list_for_suite

Response

Name	Datatype	Description
check_runs	array
total_count	integer

list_for_ref

Response

Name	Datatype	Description
check_runs	array
total_count	integer

Methods

The following methods are available for this resource:

Name	Accessible by	Required Params	Optional Params	Description
get	select	owner, repo, check_run_id		Gets a single check run 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. OAuth app tokens and personal access tokens (classic) need the repo scope to use this endpoint on a private repository.
list_for_suite	select	owner, repo, check_suite_id	check_name, status, filter, per_page, page	Lists check runs for a check suite using its id. > [!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. OAuth app tokens and personal access tokens (classic) need the repo scope to use this endpoint on a private repository.
list_for_ref	select	owner, repo, ref	check_name, status, filter, per_page, page, app_id	Lists check runs 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. If there are more than 1000 check suites on a single git reference, this endpoint will limit check runs to the 1000 most recent check suites. To iterate over all possible check runs, use the List check suites for a Git reference endpoint and provide the check_suite_id parameter to the List check runs in a check suite endpoint. OAuth app tokens and personal access tokens (classic) need the repo scope to use this endpoint on a private repository.
create	insert	owner, repo, name, head_sha, status, conclusion		Creates a new check run for a specific commit in a repository. To create a check run, you must use a GitHub App. OAuth apps and authenticated users are not able to create a check suite. In a check suite, GitHub limits the number of check runs with the same name to 1000. Once these check runs exceed 1000, GitHub will start to automatically delete older check runs. > [!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.
update	update	owner, repo, check_run_id, conclusion		Updates a check run for a specific commit in a repository. > [!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. OAuth apps and personal access tokens (classic) cannot use this endpoint.
rerequest_run	exec	owner, repo, check_run_id		Triggers GitHub to rerequest an existing check run, without pushing new code to a repository. This endpoint will trigger the check_run webhook event with the action rerequested. When a check run is rerequested, the status of the check suite it belongs to is reset to queued and the conclusion is cleared. The check run itself is not updated. GitHub apps recieving the check_run webhook with the rerequested action should then decide if the check run should be reset or updated and call the update check_run endpoint to update the check_run if desired. For more information about how to re-run GitHub Actions jobs, see "Re-run a job from a workflow run".

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_run_id	integer	The unique identifier of the check run.
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
check_name	string	Returns check runs with the specified name.
filter	string	Filters check runs by their completed_at timestamp. latest returns the most recent check runs.
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."
status	string	Returns check runs with the specified status.

SELECT examples

get

Gets a single check run 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.

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

SELECT
id,
name,
external_id,
node_id,
app,
check_suite,
completed_at,
conclusion,
deployment,
details_url,
head_sha,
html_url,
output,
pull_requests,
started_at,
status,
url
FROM github.checks.runs
WHERE owner = '{{ owner }}' -- required
AND repo = '{{ repo }}' -- required
AND check_run_id = '{{ check_run_id }}' -- required
;

list_for_suite

Lists check runs for a check suite using its id.

> [!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.

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

SELECT
check_runs,
total_count
FROM github.checks.runs
WHERE owner = '{{ owner }}' -- required
AND repo = '{{ repo }}' -- required
AND check_suite_id = '{{ check_suite_id }}' -- required
AND check_name = '{{ check_name }}'
AND status = '{{ status }}'
AND filter = '{{ filter }}'
AND per_page = '{{ per_page }}'
AND page = '{{ page }}'
;

list_for_ref

Lists check runs 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.

If there are more than 1000 check suites on a single git reference, this endpoint will limit check runs to the 1000 most recent check suites. To iterate over all possible check runs, use the List check suites for a Git reference endpoint and provide the check_suite_id parameter to the List check runs in a check suite endpoint.

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

SELECT
check_runs,
total_count
FROM github.checks.runs
WHERE owner = '{{ owner }}' -- required
AND repo = '{{ repo }}' -- required
AND ref = '{{ ref }}' -- required
AND check_name = '{{ check_name }}'
AND status = '{{ status }}'
AND filter = '{{ filter }}'
AND per_page = '{{ per_page }}'
AND page = '{{ page }}'
AND app_id = '{{ app_id }}'
;

INSERT examples

create

Creates a new check run for a specific commit in a repository.

To create a check run, you must use a GitHub App. OAuth apps and authenticated users are not able to create a check suite.

In a check suite, GitHub limits the number of check runs with the same name to 1000. Once these check runs exceed 1000, GitHub will start to automatically delete older check runs.

> [!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.

INSERT INTO github.checks.runs (
name,
head_sha,
details_url,
external_id,
status,
started_at,
conclusion,
completed_at,
output,
actions,
owner,
repo
)
SELECT 
'{{ name }}' /* required */,
'{{ head_sha }}' /* required */,
'{{ details_url }}',
'{{ external_id }}',
'{{ status }}' /* required */,
'{{ started_at }}',
'{{ conclusion }}' /* required */,
'{{ completed_at }}',
'{{ output }}',
'{{ actions }}',
'{{ owner }}',
'{{ repo }}'
RETURNING
id,
name,
external_id,
node_id,
app,
check_suite,
completed_at,
conclusion,
deployment,
details_url,
head_sha,
html_url,
output,
pull_requests,
started_at,
status,
url
;

Manifest

# Description fields are for documentation purposes
- name: runs
props:
  - name: owner
    value: "{{ owner }}"
    description: Required parameter for the runs resource.
  - name: repo
    value: "{{ repo }}"
    description: Required parameter for the runs resource.
  - name: name
    value: "{{ name }}"
    description: |
      The name of the check. For example, "code-coverage".
  - name: head_sha
    value: "{{ head_sha }}"
    description: |
      The SHA of the commit.
  - name: details_url
    value: "{{ details_url }}"
    description: |
      The URL of the integrator's site that has the full details of the check. If the integrator does not provide this, then the homepage of the GitHub app is used.
  - name: external_id
    value: "{{ external_id }}"
    description: |
      A reference for the run on the integrator's system.
  - name: status
    value: "{{ status }}"
    description: |
      The current status of the check run. Only GitHub Actions can set a status of `waiting`, `pending`, or `requested`.
    valid_values: ['queued', 'in_progress', 'completed', 'waiting', 'requested', 'pending']
    default: queued
  - name: started_at
    value: "{{ started_at }}"
    description: |
      The time that the check run began. This is a timestamp in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format: `YYYY-MM-DDTHH:MM:SSZ`.
  - name: conclusion
    value: "{{ conclusion }}"
    description: |
      **Required if you provide `completed_at` or a `status` of `completed`**. The final conclusion of the check.
      **Note:** Providing `conclusion` will automatically set the `status` parameter to `completed`. You cannot change a check run conclusion to `stale`, only GitHub can set this.
    valid_values: ['action_required', 'cancelled', 'failure', 'neutral', 'success', 'skipped', 'stale', 'timed_out']
  - name: completed_at
    value: "{{ completed_at }}"
    description: |
      The time the check completed. This is a timestamp in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format: `YYYY-MM-DDTHH:MM:SSZ`.
  - name: output
    description: |
      Check runs can accept a variety of data in the `output` object, including a `title` and `summary` and can optionally provide descriptive details about the run.
    value:
      title: "{{ title }}"
      summary: "{{ summary }}"
      text: "{{ text }}"
      annotations:
        - path: "{{ path }}"
          start_line: {{ start_line }}
          end_line: {{ end_line }}
          start_column: {{ start_column }}
          end_column: {{ end_column }}
          annotation_level: "{{ annotation_level }}"
          message: "{{ message }}"
          title: "{{ title }}"
          raw_details: "{{ raw_details }}"
      images:
        - alt: "{{ alt }}"
          image_url: "{{ image_url }}"
          caption: "{{ caption }}"
  - name: actions
    description: |
      Displays a button on GitHub that can be clicked to alert your app to do additional tasks. For example, a code linting app can display a button that automatically fixes detected errors. The button created in this object is displayed after the check run completes. When a user clicks the button, GitHub sends the [`check_run.requested_action` webhook](https://docs.github.com/webhooks/event-payloads/#check_run) to your app. Each action includes a `label`, `identifier` and `description`. A maximum of three actions are accepted. To learn more about check runs and requested actions, see "[Check runs and requested actions](https://docs.github.com/rest/guides/using-the-rest-api-to-interact-with-checks#check-runs-and-requested-actions)."
    value:
      - label: "{{ label }}"
        description: "{{ description }}"
        identifier: "{{ identifier }}"

UPDATE examples

update

Updates a check run for a specific commit in a repository.

> [!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.

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

UPDATE github.checks.runs
SET 
name = '{{ name }}',
details_url = '{{ details_url }}',
external_id = '{{ external_id }}',
started_at = '{{ started_at }}',
status = '{{ status }}',
conclusion = '{{ conclusion }}',
completed_at = '{{ completed_at }}',
output = '{{ output }}',
actions = '{{ actions }}'
WHERE 
owner = '{{ owner }}' --required
AND repo = '{{ repo }}' --required
AND check_run_id = '{{ check_run_id }}' --required
AND conclusion = '{{ conclusion }}' --required
RETURNING
id,
name,
external_id,
node_id,
app,
check_suite,
completed_at,
conclusion,
deployment,
details_url,
head_sha,
html_url,
output,
pull_requests,
started_at,
status,
url;

Lifecycle Methods

rerequest_run

Triggers GitHub to rerequest an existing check run, without pushing new code to a repository. This endpoint will trigger the check_run webhook event with the action rerequested. When a check run is rerequested, the status of the check suite it belongs to is reset to queued and the conclusion is cleared. The check run itself is not updated. GitHub apps recieving the check_run webhook with the rerequested action should then decide if the check run should be reset or updated and call the update check_run endpoint to update the check_run if desired.

For more information about how to re-run GitHub Actions jobs, see "Re-run a job from a workflow run".

EXEC github.checks.runs.rerequest_run 
@owner='{{ owner }}' --required, 
@repo='{{ repo }}' --required, 
@check_run_id='{{ check_run_id }}' --required
;