checks

Create a check run

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.

Creates a new check run for a specific commit in a repository. Your GitHub App must have the checks:write permission to create check runs.

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.

octokit.checks.create({
        owner,
repo,
name,
head_sha,
output.title,
output.summary,
output.annotations[].path,
output.annotations[].start_line,
output.annotations[].end_line,
output.annotations[].annotation_level,
output.annotations[].message,
output.images[].alt,
output.images[].image_url,
actions[].label,
actions[].description,
actions[].identifier
      })

Parameters

name	required	description
owner	yes
repo	yes
name	yes	The name of the check. For example, "code-coverage".
head_sha	yes	The SHA of the commit.
details_url	no	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.
external_id	no	A reference for the run on the integrator's system.
status	no	The current status. Can be one of `queued`, `in_progress`, or `completed`.
started_at	no	The time that the check run began. This is a timestamp in ISO 8601 format: `YYYY-MM-DDTHH:MM:SSZ`.
conclusion	no	Required if you provide `completed_at` or a `status` of `completed`. The final conclusion of the check. Can be one of `action_required`, `cancelled`, `failure`, `neutral`, `success`, `skipped`, `stale`, or `timed_out`. When the conclusion is `action_required`, additional details should be provided on the site specified by `details_url`.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.
completed_at	no	The time the check completed. This is a timestamp in ISO 8601 format: `YYYY-MM-DDTHH:MM:SSZ`.
output	no	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. See the `output` object description.
output.title	yes	The title of the check run.
output.summary	yes	The summary of the check run. This parameter supports Markdown.
output.text	no	The details of the check run. This parameter supports Markdown.
output.annotations	no	Adds information from your analysis to specific lines of code. Annotations are visible on GitHub in the Checks and Files changed tab of the pull request. The Checks API limits the number of annotations to a maximum of 50 per API request. To create more than 50 annotations, you have to make multiple requests to the Update a check run endpoint. Each time you update the check run, annotations are appended to the list of annotations that already exist for the check run. For details about how you can view annotations on GitHub, see "About status checks". See the `annotations` object description for details about how to use this parameter.
output.annotations[].path	yes	The path of the file to add an annotation to. For example, `assets/css/main.css`.
output.annotations[].start_line	yes	The start line of the annotation.
output.annotations[].end_line	yes	The end line of the annotation.
output.annotations[].start_column	no	The start column of the annotation. Annotations only support `start_column` and `end_column` on the same line. Omit this parameter if `start_line` and `end_line` have different values.
output.annotations[].end_column	no	The end column of the annotation. Annotations only support `start_column` and `end_column` on the same line. Omit this parameter if `start_line` and `end_line` have different values.
output.annotations[].annotation_level	yes	The level of the annotation. Can be one of `notice`, `warning`, or `failure`.
output.annotations[].message	yes	A short description of the feedback for these lines of code. The maximum size is 64 KB.
output.annotations[].title	no	The title that represents the annotation. The maximum size is 255 characters.
output.annotations[].raw_details	no	Details about this annotation. The maximum size is 64 KB.
output.images	no	Adds images to the output displayed in the GitHub pull request UI. See the `images` object description for details.
output.images[].alt	yes	The alternative text for the image.
output.images[].image_url	yes	The full URL of the image.
output.images[].caption	no	A short image description.
actions	no	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 to your app. Each action includes a `label`, `identifier` and `description`. A maximum of three actions are accepted. See the `actions` object description. To learn more about check runs and requested actions, see "Check runs and requested actions." To learn more about check runs and requested actions, see "Check runs and requested actions."
actions[].label	yes	The text to be displayed on a button in the web UI. The maximum size is 20 characters.
actions[].description	yes	A short explanation of what this action would do. The maximum size is 40 characters.
actions[].identifier	yes	A reference for the action on the integrator's system. The maximum size is 20 characters.

Create a check suite

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". Your GitHub App must have the checks:write permission to create check suites.

octokit.checks.createSuite({
  owner,
  repo,
  head_sha,
});

Parameters

name	required	description
owner	yes
repo	yes
head_sha	yes	The sha of the head commit.

Get a check run

Gets a single check run using its id. GitHub Apps must have the checks:read permission on a private repository or pull access to a public repository to get check runs. OAuth Apps and authenticated users must have the repo scope to get check runs in a private repository.

octokit.checks.get({
  owner,
  repo,
  check_run_id,
});

Parameters

name	required	description
owner	yes
repo	yes
check_run_id	yes	check_run_id parameter

Get a check suite

Gets a single check suite using its id. GitHub Apps must have the checks:read permission on a private repository or pull access to a public repository to get check suites. OAuth Apps and authenticated users must have the repo scope to get check suites in a private repository.

octokit.checks.getSuite({
  owner,
  repo,
  check_suite_id,
});

Parameters

name	required	description
owner	yes
repo	yes
check_suite_id	yes	check_suite_id parameter

List check run annotations

Lists annotations for a check run using the annotation id. GitHub Apps must have the checks:read permission on a private repository or pull access to a public repository to get annotations for a check run. OAuth Apps and authenticated users must have the repo scope to get annotations for a check run in a private repository.

octokit.checks.listAnnotations({
  owner,
  repo,
  check_run_id,
});

Parameters

name	required	description
owner	yes
repo	yes
check_run_id	yes	check_run_id parameter
per_page	no	Results per page (max 100)
page	no	Page number of the results to fetch.

List check runs for a Git reference

Lists check runs for a commit ref. The ref can be a SHA, branch name, or a tag name. GitHub Apps must have the checks:read permission on a private repository or pull access to a public repository to get check runs. OAuth Apps and authenticated users must have the repo scope to get check runs in a private repository.

octokit.checks.listForRef({
  owner,
  repo,
  ref,
});

Parameters

name	required	description
owner	yes
repo	yes
ref	yes	ref+ parameter
check_name	no	Returns check runs with the specified `name`.
status	no	Returns check runs with the specified `status`. Can be one of `queued`, `in_progress`, or `completed`.
filter	no	Filters check runs by their `completed_at` timestamp. Can be one of `latest` (returning the most recent check runs) or `all`.
per_page	no	Results per page (max 100)
page	no	Page number of the results to fetch.

List check runs in a check suite

Lists check runs for a check suite using its id. GitHub Apps must have the checks:read permission on a private repository or pull access to a public repository to get check runs. OAuth Apps and authenticated users must have the repo scope to get check runs in a private repository.

octokit.checks.listForSuite({
  owner,
  repo,
  check_suite_id,
});

Parameters

name	required	description
owner	yes
repo	yes
check_suite_id	yes	check_suite_id parameter
check_name	no	Returns check runs with the specified `name`.
status	no	Returns check runs with the specified `status`. Can be one of `queued`, `in_progress`, or `completed`.
filter	no	Filters check runs by their `completed_at` timestamp. Can be one of `latest` (returning the most recent check runs) or `all`.
per_page	no	Results per page (max 100)
page	no	Page number of the results to fetch.

List check suites for a Git reference

Lists check suites for a commit ref. The ref can be a SHA, branch name, or a tag name. GitHub Apps must have the checks:read permission on a private repository or pull access to a public repository to list check suites. OAuth Apps and authenticated users must have the repo scope to get check suites in a private repository.

octokit.checks.listSuitesForRef({
  owner,
  repo,
  ref,
});

Parameters

name	required	description
owner	yes
repo	yes
ref	yes	ref+ parameter
app_id	no	Filters check suites by GitHub App `id`.
check_name	no	Returns check runs with the specified `name`.
per_page	no	Results per page (max 100)
page	no	Page number of the results to fetch.

Rerequest a check 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.

To rerequest a check suite, your GitHub App must have the checks:read permission on a private repository or pull access to a public repository.

octokit.checks.rerequestSuite({
  owner,
  repo,
  check_suite_id,
});

Parameters

name	required	description
owner	yes
repo	yes
check_suite_id	yes	check_suite_id parameter

Update repository preferences for check suites

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.

octokit.checks.setSuitesPreferences({
        owner,
repo,
auto_trigger_checks[].app_id,
auto_trigger_checks[].setting
      })

Parameters

name	required	description
owner	yes
repo	yes
auto_trigger_checks	no	Enables or disables automatic creation of CheckSuite events upon pushes to the repository. Enabled by default. See the `auto_trigger_checks` object description for details.
auto_trigger_checks[].app_id	yes	The `id` of the GitHub App.
auto_trigger_checks[].setting	yes	Set to `true` to enable automatic creation of CheckSuite events upon pushes to the repository, or `false` to disable them.

Update a check run

Updates a check run for a specific commit in a repository. Your GitHub App must have the checks:write permission to edit check runs.

octokit.checks.update({
        owner,
repo,
check_run_id,
output.summary,
output.annotations[].path,
output.annotations[].start_line,
output.annotations[].end_line,
output.annotations[].annotation_level,
output.annotations[].message,
output.images[].alt,
output.images[].image_url,
actions[].label,
actions[].description,
actions[].identifier
      })

Parameters

name	required	description
owner	yes
repo	yes
check_run_id	yes	check_run_id parameter
name	no	The name of the check. For example, "code-coverage".
details_url	no	The URL of the integrator's site that has the full details of the check.
external_id	no	A reference for the run on the integrator's system.
started_at	no	This is a timestamp in ISO 8601 format: `YYYY-MM-DDTHH:MM:SSZ`.
status	no	The current status. Can be one of `queued`, `in_progress`, or `completed`.
conclusion	no	Required if you provide `completed_at` or a `status` of `completed`. The final conclusion of the check. Can be one of `action_required`, `cancelled`, `failure`, `neutral`, `success`, `skipped`, `stale`, or `timed_out`.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.
completed_at	no	The time the check completed. This is a timestamp in ISO 8601 format: `YYYY-MM-DDTHH:MM:SSZ`.
output	no	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. See the `output` object description.
output.title	no	Required.
output.summary	yes	Can contain Markdown.
output.text	no	Can contain Markdown.
output.annotations	no	Adds information from your analysis to specific lines of code. Annotations are visible in GitHub's pull request UI. Annotations are visible in GitHub's pull request UI. The Checks API limits the number of annotations to a maximum of 50 per API request. To create more than 50 annotations, you have to make multiple requests to the Update a check run endpoint. Each time you update the check run, annotations are appended to the list of annotations that already exist for the check run. For details about annotations in the UI, see "About status checks". See the `annotations` object description for details.
output.annotations[].path	yes	The path of the file to add an annotation to. For example, `assets/css/main.css`.
output.annotations[].start_line	yes	The start line of the annotation.
output.annotations[].end_line	yes	The end line of the annotation.
output.annotations[].start_column	no	The start column of the annotation. Annotations only support `start_column` and `end_column` on the same line. Omit this parameter if `start_line` and `end_line` have different values.
output.annotations[].end_column	no	The end column of the annotation. Annotations only support `start_column` and `end_column` on the same line. Omit this parameter if `start_line` and `end_line` have different values.
output.annotations[].annotation_level	yes	The level of the annotation. Can be one of `notice`, `warning`, or `failure`.
output.annotations[].message	yes	A short description of the feedback for these lines of code. The maximum size is 64 KB.
output.annotations[].title	no	The title that represents the annotation. The maximum size is 255 characters.
output.annotations[].raw_details	no	Details about this annotation. The maximum size is 64 KB.
output.images	no	Adds images to the output displayed in the GitHub pull request UI. See the `images` object description for details.
output.images[].alt	yes	The alternative text for the image.
output.images[].image_url	yes	The full URL of the image.
output.images[].caption	no	A short image description.
actions	no	Possible further actions the integrator can perform, which a user may trigger. Each action includes a `label`, `identifier` and `description`. A maximum of three actions are accepted. See the `actions` object description. To learn more about check runs and requested actions, see "Check runs and requested actions."
actions[].label	yes	The text to be displayed on a button in the web UI. The maximum size is 20 characters.
actions[].description	yes	A short explanation of what this action would do. The maximum size is 40 characters.
actions[].identifier	yes	A reference for the action on the integrator's system. The maximum size is 20 characters.

Octokit Rest API

Create a check run

Parameters

Create a check suite

Parameters

Get a check run

Parameters

Get a check suite

Parameters

List check run annotations

Parameters

List check runs for a Git reference

Parameters

List check runs in a check suite

Parameters

List check suites for a Git reference

Parameters

Rerequest a check suite

Parameters

Update repository preferences for check suites

Parameters

Update a check run

Parameters