Article version

Enterprise Server 2.22

Checks

The Checks API enables you to build GitHub Apps that run powerful checks against code changes in a repository. You can create apps that perform continuous integration, code linting, or code scanning services and provide detailed feedback on commits. For more information, see "Getting started with the checks API" and "Creating CI tests with the Checks API."

Check Runs

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.

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

Parameters

Name Type In Description

accept

string

header

This API is under preview and subject to change.See preview notice

owner string path

repo string path

name

string

body

Required. The name of the check. For example, "code-coverage".

head_sha

string

body

Required. The SHA of the commit.

details_url

string

body

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

string

body

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

status

string

body

The current status. Can be one of queued, in_progress, or completed.

Default: queued

started_at

string

body

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

conclusion

string

body

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

string

body

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

output

object

body

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.

Properties of the output object

`title` (string)	Required. The title of the check run.
`summary` (string)	Required. The summary of the check run. This parameter supports Markdown.
`text` (string)	The details of the check run. This parameter supports Markdown.
`annotations` (array of objects)	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.
`images` (array of objects)	Adds images to the output displayed in the GitHub pull request UI. See the `images` object description for details.

Properties of the annotations items

`path` (string)	Required. The path of the file to add an annotation to. For example, `assets/css/main.css`.
`start_line` (integer)	Required. The start line of the annotation.
`end_line` (integer)	Required. The end line of the annotation.
`start_column` (integer)	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.
`end_column` (integer)	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.
`annotation_level` (string)	Required. The level of the annotation. Can be one of `notice`, `warning`, or `failure`.
`message` (string)	Required. A short description of the feedback for these lines of code. The maximum size is 64 KB.
`title` (string)	The title that represents the annotation. The maximum size is 255 characters.
`raw_details` (string)	Details about this annotation. The maximum size is 64 KB.

Properties of the images items

`alt` (string)	Required. The alternative text for the image.
`image_url` (string)	Required. The full URL of the image.
`caption` (string)	A short image description.

actions

array of objects

body

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

Properties of the actions items

`label` (string)	Required. The text to be displayed on a button in the web UI. The maximum size is 20 characters.
`description` (string)	Required. A short explanation of what this action would do. The maximum size is 40 characters.
`identifier` (string)	Required. A reference for the action on the integrator's system. The maximum size is 20 characters.

Code samples

Shell

curl \
  -X POST \
  -H "Accept: application/vnd.github.antiope-preview+json" \
  http(s)://{hostname}/api/v3/repos/octocat/hello-world/check-runs \
  -d '{"name":"name","head_sha":"head_sha"}'

JavaScript (@octokit/core.js)

await octokit.request('POST /repos/{owner}/{repo}/check-runs', {
  owner: 'octocat',
  repo: 'hello-world',
  name: 'name',
  head_sha: 'head_sha',
  mediaType: {
    previews: [
      'antiope'
    ]
  }
})

Response for completed conclusion

Status: 201 Created

{
  "id": 4,
  "head_sha": "ce587453ced02b1526dfb4cb910479d431683101",
  "node_id": "MDg6Q2hlY2tSdW40",
  "external_id": "",
  "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":

Explore by product

In this article

Checks

Check Runs

Create a check run

Parameters

Code samples

Shell

JavaScript (@octokit/core.js)

Response for completed conclusion