Skip to content
forgit api docs

Create a check run

POST
/repos/{owner}/{repo}/check-runs

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.

API method documentation

Parameters

Section titled “ Parameters ”

Path Parameters

Section titled “ Path Parameters ”
owner
required
string

The account owner of the repository. The name is not case sensitive.

repo
required
string

The name of the repository without the .git extension. The name is not case sensitive.

Request Body required

Section titled “ Request Body required ”
Media type application/json
One of: discriminator: status
object
name
required

The name of the check. For example, “code-coverage”.

string
head_sha
required

The SHA of the commit.

string
details_url

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.

string
external_id

A reference for the run on the integrator’s system.

string
status
required
Allowed values: completed
started_at

The time that the check run began. This is a timestamp in ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ.

string format: date-time
conclusion
required

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.

string
Allowed values: action_required cancelled failure neutral success skipped stale timed_out
completed_at

The time the check completed. This is a timestamp in ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ.

string format: date-time
output

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.

object
title
required

The title of the check run.

string
summary
required

The summary of the check run. This parameter supports Markdown. Maximum length: 65535 characters.

string
<= 65535 characters
text

The details of the check run. This parameter supports Markdown. Maximum length: 65535 characters.

string
<= 65535 characters
annotations

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. 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”.

Array<object>
<= 50 items
object
path
required

The path of the file to add an annotation to. For example, assets/css/main.css.

string
start_line
required

The start line of the annotation. Line numbers start at 1.

integer
end_line
required

The end line of the annotation.

integer
start_column

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.

integer
end_column

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.

integer
annotation_level
required

The level of the annotation.

string
Allowed values: notice warning failure
message
required

A short description of the feedback for these lines of code. The maximum size is 64 KB.

string
title

The title that represents the annotation. The maximum size is 255 characters.

string
raw_details

Details about this annotation. The maximum size is 64 KB.

string
images

Adds images to the output displayed in the GitHub pull request UI.

Array<object>
object
alt
required

The alternative text for the image.

string
image_url
required

The full URL of the image.

string
caption

A short image description.

string
actions

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. To learn more about check runs and requested actions, see “Check runs and requested actions.”

Array<object>
<= 3 items
object
label
required

The text to be displayed on a button in the web UI. The maximum size is 20 characters.

string
<= 20 characters
description
required

A short explanation of what this action would do. The maximum size is 40 characters.

string
<= 40 characters
identifier
required

A reference for the action on the integrator’s system. The maximum size is 20 characters.

string
<= 20 characters
key
additional properties
any
Examples

Example of an in_progress conclusion 

{
  "name": "mighty_readme",
  "head_sha": "ce587453ced02b1526dfb4cb910479d431683101",
  "status": "in_progress",
  "external_id": "42",
  "started_at": "2018-05-04T01:14:52Z",
  "output": {
    "title": "Mighty Readme report",
    "summary": "",
    "text": ""
  }
}

Responses

Section titled “ Responses ”

201

Section titled “ 201 ”

Response

Media type application/json
CheckRun

A check performed on the code of a given code change

object
id
required

The id of the check.

integer format: int64
head_sha
required

The SHA of the commit that is being checked.

string
node_id
required
string
external_id
required
string
nullable
url
required
string
html_url
required
string
nullable
details_url
required
string
nullable
status
required

The phase of the lifecycle that the check is currently in. Statuses of waiting, requested, and pending are reserved for GitHub Actions check runs.

string
Allowed values: queued in_progress completed waiting requested pending
conclusion
required
string
nullable
Allowed values: success failure neutral cancelled skipped timed_out action_required
started_at
required
string format: date-time
nullable
completed_at
required
string format: date-time
nullable
output
required
object
title
required
string
nullable
summary
required
string
nullable
text
required
string
nullable
annotations_count
required
integer
annotations_url
required
string format: uri
name
required

The name of the check.

string
check_suite
required
object
id
required
integer
app
required
GitHub app

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.

object
id
required

Unique identifier of the GitHub app

integer
slug

The slug name of the GitHub app

string
node_id
required
string
client_id
string
owner
required
One of:
Simple User

A GitHub user.

object
name
string
nullable
email
string
nullable
login
required
string
id
required
integer format: int64
node_id
required
string
avatar_url
required
string format: uri
gravatar_id
required
string
nullable
url
required
string format: uri
html_url
required
string format: uri
followers_url
required
string format: uri
following_url
required
string
gists_url
required
string
starred_url
required
string
subscriptions_url
required
string format: uri
organizations_url
required
string format: uri
repos_url
required
string format: uri
events_url
required
string
received_events_url
required
string format: uri
type
required
string
site_admin
required
boolean
starred_at
string
user_view_type
string
name
required

The name of the GitHub app

string
description
required
string
nullable
external_url
required
string format: uri
html_url
required
string format: uri
created_at
required
string format: date-time
updated_at
required
string format: date-time
permissions
required

The set of permissions for the GitHub app

object
issues
string
checks
string
metadata
string
contents
string
deployments
string
key
additional properties
string
events
required

The list of events for the GitHub app. Note that the installation_target, security_advisory, and meta events are not included because they are global events and not specific to an installation.

Array<string>
installations_count

The number of installations associated with the GitHub app. Only returned when the integration is requesting details about itself.

integer
pull_requests
required

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.

Array<object>
Pull Request Minimal
object
id
required
integer format: int64
number
required
integer
url
required
string
head
required
object
ref
required
string
sha
required
string
repo
required
object
id
required
integer format: int64
url
required
string
name
required
string
base
required
object
ref
required
string
sha
required
string
repo
required
object
id
required
integer format: int64
url
required
string
name
required
string
deployment
Deployment

A deployment created as the result of an Actions check run from a workflow that references an environment

object
url
required
string format: uri
id
required

Unique identifier of the deployment

integer
node_id
required
string
task
required

Parameter to specify a task to execute

string
original_environment
string
environment
required

Name for the target deployment environment.

string
description
required
string
nullable
created_at
required
string format: date-time
updated_at
required
string format: date-time
statuses_url
required
string format: uri
repository_url
required
string format: uri
transient_environment

Specifies if the given environment is will no longer exist at some point in the future. Default: false.

boolean
production_environment

Specifies if the given environment is one that end-users directly interact with. Default: false.

boolean
performed_via_github_app
GitHub app

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.

object
id
required

Unique identifier of the GitHub app

integer
slug

The slug name of the GitHub app

string
node_id
required
string
client_id
string
owner
required
One of:
Simple User

A GitHub user.

object
name
string
nullable
email
string
nullable
login
required
string
id
required
integer format: int64
node_id
required
string
avatar_url
required
string format: uri
gravatar_id
required
string
nullable
url
required
string format: uri
html_url
required
string format: uri
followers_url
required
string format: uri
following_url
required
string
gists_url
required
string
starred_url
required
string
subscriptions_url
required
string format: uri
organizations_url
required
string format: uri
repos_url
required
string format: uri
events_url
required
string
received_events_url
required
string format: uri
type
required
string
site_admin
required
boolean
starred_at
string
user_view_type
string
name
required

The name of the GitHub app

string
description
required
string
nullable
external_url
required
string format: uri
html_url
required
string format: uri
created_at
required
string format: date-time
updated_at
required
string format: date-time
permissions
required

The set of permissions for the GitHub app

object
issues
string
checks
string
metadata
string
contents
string
deployments
string
key
additional properties
string
events
required

The list of events for the GitHub app. Note that the installation_target, security_advisory, and meta events are not included because they are global events and not specific to an installation.

Array<string>
installations_count

The number of installations associated with the GitHub app. Only returned when the integration is requesting details about itself.

integer
Examples

Response for completed conclusion 

{
  "id": 4,
  "head_sha": "ce587453ced02b1526dfb4cb910479d431683101",
  "node_id": "MDg6Q2hlY2tSdW40",
  "external_id": "42",
  "url": "https://api.github.com/repos/github/hello-world/check-runs/4",
  "html_url": "https://github.com/github/hello-world/runs/4",
  "details_url": "https://example.com",
  "status": "completed",
  "conclusion": "neutral",
  "started_at": "2018-05-04T01:14:52Z",
  "completed_at": "2018-05-04T01:14:52Z",
  "output": {
    "title": "Mighty Readme report",
    "summary": "There are 0 failures, 2 warnings, and 1 notice.",
    "text": "You may have some misspelled words on lines 2 and 4. You also may want to add a section in your README about how to install your app.",
    "annotations_count": 2,
    "annotations_url": "https://api.github.com/repos/github/hello-world/check-runs/4/annotations"
  },
  "name": "mighty_readme",
  "check_suite": {
    "id": 5
  },
  "app": {
    "id": 1,
    "slug": "octoapp",
    "node_id": "MDExOkludGVncmF0aW9uMQ==",
    "owner": {
      "login": "github",
      "id": 1,
      "node_id": "MDEyOk9yZ2FuaXphdGlvbjE=",
      "url": "https://api.github.com/orgs/github",
      "repos_url": "https://api.github.com/orgs/github/repos",
      "events_url": "https://api.github.com/orgs/github/events",
      "avatar_url": "https://github.com/images/error/octocat_happy.gif",
      "gravatar_id": "",
      "html_url": "https://github.com/octocat",
      "followers_url": "https://api.github.com/users/octocat/followers",
      "following_url": "https://api.github.com/users/octocat/following{/other_user}",
      "gists_url": "https://api.github.com/users/octocat/gists{/gist_id}",
      "starred_url": "https://api.github.com/users/octocat/starred{/owner}{/repo}",
      "subscriptions_url": "https://api.github.com/users/octocat/subscriptions",
      "organizations_url": "https://api.github.com/users/octocat/orgs",
      "received_events_url": "https://api.github.com/users/octocat/received_events",
      "type": "User",
      "site_admin": true
    },
    "name": "Octocat App",
    "description": "",
    "external_url": "https://example.com",
    "html_url": "https://github.com/apps/octoapp",
    "created_at": "2017-07-08T16:18:44-04:00",
    "updated_at": "2017-07-08T16:18:44-04:00",
    "permissions": {
      "metadata": "read",
      "contents": "read",
      "issues": "write",
      "single_file": "write"
    },
    "events": [
      "push",
      "pull_request"
    ]
  },
  "pull_requests": [
    {
      "url": "https://api.github.com/repos/github/hello-world/pulls/1",
      "id": 1934,
      "number": 3956,
      "head": {
        "ref": "say-hello",
        "sha": "3dca65fa3e8d4b3da3f3d056c59aee1c50f41390",
        "repo": {
          "id": 526,
          "url": "https://api.github.com/repos/github/hello-world",
          "name": "hello-world"
        }
      },
      "base": {
        "ref": "master",
        "sha": "e7fdf7640066d71ad16a86fbcbb9c6a10a18af4f",
        "repo": {
          "id": 526,
          "url": "https://api.github.com/repos/github/hello-world",
          "name": "hello-world"
        }
      }
    }
  ]
}