GitHub: Create a check run

← Checks operations · Get started

Operation github.checks_create

Provider route: POST /repos/{owner}/{repo}/check-runs. Alter supplies the connection’s credentials and routing.

Call through Alter

Install @alter-ai/sdk @alter-ai/github with npm, or alter-sdk-github with pip. Supply your connected customer’s grant ID and the arguments described below.

import { App } from "@alter-ai/sdk";
import { GitHubIntegration } from "@alter-ai/github";

async function execute(input: Parameters<GitHubIntegration["checks"]["checksCreate"]>[0]) {
  const app = new App({ apiKey: process.env.ALTER_API_KEY! });
  try {
    const provider = new GitHubIntegration(app, { grantId: process.env.PROVIDER_GRANT_ID! });
    const call = await provider.checks.checksCreate(input);
    const result = await call.wait();
    return result.bodyJson();
  } finally {
    await app.close();
  }
}

import os
from alter_sdk import App
from alter_sdk_github import GitHubIntegration

async def execute(arguments):
    async with App(api_key=os.environ["ALTER_API_KEY"]) as app:
        provider = GitHubIntegration(app, {"grant_id": os.environ["PROVIDER_GRANT_ID"]})
        call = await provider.checks.checks_create(arguments)
        result = await call.wait()
        return result.body_json()

Input

Field	Type	Presence	Description and constraints
$	object	Root	Additional keys: not allowed
path	object	Required within parent	Additional keys: not allowed
path.owner	string	Required within parent
path.repo	string	Required within parent
body	object	Required within parent	discriminator: {“propertyName”: “status”}
body.actions	array	Optional	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).” Maximum items: 3
body.actions[]	Model	Each item	Expand Create a check run — request body — body actions item
body.completed_at	string	Optional	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`. Format: date-time
body.conclusion	string	Optional	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. One of: action_required, cancelled, failure, neutral, success, skipped, stale, timed_out
body.details_url	string	Optional	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.
body.external_id	string	Optional	A reference for the run on the integrator’s system.
body.head_sha	string	Required within parent	The SHA of the commit.
body.name	string	Required within parent	The name of the check. For example, “code-coverage”.
body.output	object	Optional	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.
body.output.annotations	array	Optional	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](https://docs.github.com/rest/checks/runs#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. GitHub Actions are limited to 10 warning annotations and 10 error annotations per step. For details about how you can view annotations on GitHub, see “[About status checks](https://docs.github.com/articles/about-status-checks#checks)”. Maximum items: 50
body.output.annotations[]	Model	Each item	Expand Create a check run — request body — body output annotations item
body.output.images	array	Optional	Adds images to the output displayed in the GitHub pull request UI.
body.output.images[]	object	Each item
body.output.images[].alt	string	Required within parent	The alternative text for the image.
body.output.images[].caption	string	Optional	A short image description.
body.output.images[].image_url	string	Required within parent	The full URL of the image.
body.output.summary	string	Required within parent	The summary of the check run. This parameter supports Markdown. Maximum length: 65535 characters. Maximum length: 65535
body.output.text	string	Optional	The details of the check run. This parameter supports Markdown. Maximum length: 65535 characters. Maximum length: 65535
body.output.title	string	Required within parent	The title of the check run.
body.started_at	string	Optional	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`. Format: date-time
body.status	string	Optional	The current status of the check run. Only GitHub Actions can set a status of `waiting`, `pending`, or `requested`. Default: queued One of: queued, in_progress, completed, waiting, requested, pending
body (oneOf 1)	JSON	Alternative	Additional keys: allowed
body (oneOf 1).status	JSON	Required within parent	One of: completed
body (oneOf 2)	JSON	Alternative	Additional keys: allowed
body (oneOf 2).status	JSON	Optional	One of: queued, in_progress

Referenced models: Create a check run — request body — body actions item, Create a check run — request body — body output annotations item

Response

Response media type: application/json. The table describes the pinned successful response. Referenced models link to their complete fields.

Field	Type	Presence	Description and constraints
$	Model	Root	Expand Get a check run — response body

Referenced models: Get a check run — response body

Schemas

3 more schemas are linked from the tables above, on the schema pages.

Get a check run — response body

Field	Type	Presence	Description and constraints
$	object	Root	A check performed on the code of a given code change
app	Model	Required within parent	Expand Get an app — response body
check_suite	JSON	Required within parent
check_suite (anyOf 1)	object	Alternative
check_suite (anyOf 1).id	JSON	Required within parent
check_suite (anyOf 1).id (anyOf 1)	integer	Alternative
check_suite (anyOf 1).id (anyOf 2)	string	Alternative	Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$
check_suite (anyOf 2)	null	Alternative
completed_at	JSON	Required within parent
completed_at (anyOf 1)	string	Alternative	Format: date-time
completed_at (anyOf 2)	null	Alternative
conclusion	JSON	Required within parent
conclusion (anyOf 1)	string	Alternative	Known values: success, failure, neutral, cancelled, skipped, timed_out, action_required
conclusion (anyOf 2)	null	Alternative
deployment	Model	Optional	Expand Get a check run — response body — deployment
details_url	JSON	Required within parent
details_url (anyOf 1)	string	Alternative
details_url (anyOf 2)	null	Alternative
external_id	JSON	Required within parent
external_id (anyOf 1)	string	Alternative
external_id (anyOf 2)	null	Alternative
head_sha	string	Required within parent	The SHA of the commit that is being checked.
html_url	JSON	Required within parent
html_url (anyOf 1)	string	Alternative
html_url (anyOf 2)	null	Alternative
id	JSON	Required within parent
id (anyOf 1)	integer	Alternative	The id of the check. Format: int64
id (anyOf 2)	string	Alternative	Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$
name	string	Required within parent	The name of the check.
node_id	string	Required within parent
output	object	Required within parent
output.annotations_count	JSON	Required within parent
output.annotations_count (anyOf 1)	integer	Alternative
output.annotations_count (anyOf 2)	string	Alternative	Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$
output.annotations_url	string	Required within parent	Format: uri
output.summary	JSON	Required within parent
output.summary (anyOf 1)	string	Alternative
output.summary (anyOf 2)	null	Alternative
output.text	JSON	Required within parent
output.text (anyOf 1)	string	Alternative
output.text (anyOf 2)	null	Alternative
output.title	JSON	Required within parent
output.title (anyOf 1)	string	Alternative
output.title (anyOf 2)	null	Alternative
pull_requests	array	Required within parent	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.
pull_requests[]	Model	Each item	Expand Get a check run — response body — pull requests item
started_at	JSON	Required within parent
started_at (anyOf 1)	string	Alternative	Format: date-time
started_at (anyOf 2)	null	Alternative
status	string	Required within parent	The phase of the lifecycle that the check is currently in. Statuses of waiting, requested, and pending are reserved for GitHub Actions check runs. Known values: queued, in_progress, completed, waiting, requested, pending
url	string	Required within parent

Referenced models: Get a check run — response body — deployment, Get an app — response body, Get a check run — response body — pull requests item

Create a check run — request body — body actions item

Field	Type	Presence	Description and constraints
$	object	Root
description	string	Required within parent	A short explanation of what this action would do. The maximum size is 40 characters. Maximum length: 40
identifier	string	Required within parent	A reference for the action on the integrator's system. The maximum size is 20 characters. Maximum length: 20
label	string	Required within parent	The text to be displayed on a button in the web UI. The maximum size is 20 characters. Maximum length: 20

Create a check run — request body — body output annotations item

Field	Type	Presence	Description and constraints
$	object	Root
annotation_level	string	Required within parent	The level of the annotation. One of: notice, warning, failure
end_column	integer	Optional	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.
end_line	integer	Required within parent	The end line of the annotation.
message	string	Required within parent	A short description of the feedback for these lines of code. The maximum size is 64 KB.
path	string	Required within parent	The path of the file to add an annotation to. For example, `assets/css/main.css`.
raw_details	string	Optional	Details about this annotation. The maximum size is 64 KB.
start_column	integer	Optional	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. Column numbers start at 1.
start_line	integer	Required within parent	The start line of the annotation. Line numbers start at 1.
title	string	Optional	The title that represents the annotation. The maximum size is 255 characters.

Get a check run — response body — deployment

Field	Type	Presence	Description and constraints
$	object	Root	A deployment created as the result of an Actions check run from a workflow that references an environment
created_at	string	Required within parent	Format: date-time
description	JSON	Required within parent
description (anyOf 1)	string	Alternative
description (anyOf 2)	null	Alternative
environment	string	Required within parent	Name for the target deployment environment.
id	JSON	Required within parent
id (anyOf 1)	integer	Alternative	Unique identifier of the deployment
id (anyOf 2)	string	Alternative	Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$
node_id	string	Required within parent
original_environment	string	Optional
performed_via_github_app	Model	Optional	Expand Get an app — response body
production_environment	boolean	Optional	Specifies if the given environment is one that end-users directly interact with. Default: false.
repository_url	string	Required within parent	Format: uri
statuses_url	string	Required within parent	Format: uri
task	string	Required within parent	Parameter to specify a task to execute
transient_environment	boolean	Optional	Specifies if the given environment is will no longer exist at some point in the future. Default: false.
updated_at	string	Required within parent	Format: date-time
url	string	Required within parent	Format: uri

Referenced models: Get an app — response body

Get an app — response body — client id, created at, description, events, external url, html url, id, installations count, name, node id, owner, permissions, slug, updated at owner Enterprise

Field	Type	Presence	Description and constraints
$	object	Root	An enterprise on GitHub.
avatar_url	string	Required within parent	Format: uri
created_at	JSON	Required within parent
created_at (anyOf 1)	string	Alternative	Format: date-time
created_at (anyOf 2)	null	Alternative
description	JSON	Optional
description (anyOf 1)	string	Alternative	A short description of the enterprise.
description (anyOf 2)	null	Alternative
html_url	string	Required within parent	Format: uri
id	JSON	Required within parent
id (anyOf 1)	integer	Alternative	Unique identifier of the enterprise
id (anyOf 2)	string	Alternative	Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$
name	string	Required within parent	The name of the enterprise.
node_id	string	Required within parent
slug	string	Required within parent	The slug url identifier for the enterprise.
updated_at	JSON	Required within parent
updated_at (anyOf 1)	string	Alternative	Format: date-time
updated_at (anyOf 2)	null	Alternative
website_url	JSON	Optional
website_url (anyOf 1)	string	Alternative	The enterprise's website URL. Format: uri
website_url (anyOf 2)	null	Alternative

Policy, approvals and errors

SDK function policy ID: github.checks_create. Catalog operation: checks/create. Rules can name either ID; function rules distinguish managed calls and conservatively cover raw calls sharing the route. Existing grant permissions and policy rules apply. wait() returns an immediate result or waits for a required approval; it never approves the request itself. Persist the approval ID to resume after a restart.

Provider errors retain their response; JSON decoding raises ProviderAPIError for provider failures. ManagedOperationError identifies contract/input/retention errors. See error handling and provider-specific behavior. Sensitive input may be refused before approval storage. A decoding error never resubmits a write.

Pinned headers: {"X-GitHub-Api-Version": "2026-03-10", "User-Agent": "Alter", "Accept": "application/vnd.github+json"}

Official provider source