Check Runs

Create a check run
Update a check run
List check runs for a Git reference
List check runs in a check suite
Get a check run
List check run annotations

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

Check runs workflow

When someone pushes code to a repository, GitHub creates a check suite for the last commit. GitHub Apps with the checks:write permission receive a check_suite webhook with the requested action. When your GitHub App receives the check_suite event, it can create new check runs for the latest commit. GitHub automatically adds new check runs to the correct check suite based on the check run's repository and SHA. Check suites contain one or more check runs and report a summary conclusion for all the check runs in the suite.

If a check run is in a incomplete state for more than 14 days, then the check run's conclusion becomes stale and appears on GitHub as stale with . Only GitHub can mark check runs as stale. For more information about possible conclusions of a check run, see the conclusion parameter.

As soon as you receive the check_suite webhook, you can create the check run, even if the check is not complete. You can update the status of the check run as it completes with the values queued, in_progress, or completed, and you can update the output as more details become available. A check run can contain timestamps, a link to more details on your external site, detailed annotations for specific lines of code, and information about the analysis performed.

Check run annotation

A check can also be manually re-run in the GitHub UI. See "About status checks" for more details. When this occurs, the GitHub App that created the check run will receive the check_run webhook requesting a new check run. If you create a check run without creating a check suite, GitHub creates the check suite for you automatically.

Write permission for the Checks API is only available to GitHub Apps. OAuth Apps and authenticated users can view check runs and check suites, but they are not able to create them. If you aren't building a GitHub App, you might be interested in the Statuses API.

To use the check runs API, the GitHub App must have the checks:write permission and can also subscribe to the check_run webhook.

Check runs and requested actions

When you set up a check run with requested actions (not to be confused with GitHub Actions), you can display a button in the pull request view on GitHub that allows people to request your GitHub App to perform additional tasks.

For example, a code linting app could use requested actions to display a button in a pull request to automatically fix detected syntax errors.

To create a button that can request additional actions from your app, use the actions object when you Create a check run. For example, the actions object below displays a button in a pull request with the label "Fix this." The button appears after the check run completes.

  "actions": [{
      "label": "Fix this",
      "description": "Let us fix that for you",
      "identifier": "fix_errors"
    }]

Check run requested action button

When a user clicks the button, GitHub sends the check_run.requested_action webhook to your app. When your app receives a check_run.requested_action webhook event, it can look for the requested_action.identifier key in the webhook payload to determine which button was clicked and perform the requested task.

For a detailed example of how to set up requested actions with the Checks API, see "Creating CI tests with the Checks API."

Create a check run

Note: The Checks API is currently available for developers to preview. During the preview period, the API may change without advance notice. Please see the blog post for full details. To access the API during the preview period, you must provide a custom media type in the Accept header:

application/vnd.github.antiope-preview+json

Warning: The API may change without advance notice during the preview period. Preview features are not supported for production use. If you experience any issues, contact GitHub Support or GitHub Premium Support.

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.

POST /repos/:owner/:repo/check-runs

Parameters

Name	Type	Description
`name`	`string`	Required. The name of the check. For example, "code-coverage".
`head_sha`	`string`	Required. The SHA of the commit.
`details_url`	`string`	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`	A reference for the run on the integrator's system.
`status`	`string`	The current status. Can be one of `queued`, `in_progress`, or `completed`. Default: `queued`
`started_at`	`string`	The time that the check run began. This is a timestamp in ISO 8601 format: `YYYY-MM-DDTHH:MM:SSZ`.
`conclusion`	`string`	Required if you provide `completed_at` or a `status` of `completed`. The final conclusion of the check. Can be one of `success`, `failure`, `neutral`, `cancelled`, `skipped`, `timed_out`, or `action_required`. 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`. Only GitHub can change a check run conclusion to `stale`.
`completed_at`	`string`	The time the check completed. This is a timestamp in ISO 8601 format: `YYYY-MM-DDTHH:MM:SSZ`.
`output`	`object`	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.
`actions`	`array of objects`	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."

`output` object

Name	Type	Description
`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.

`annotations` object

Name	Type	Description
`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.

`images` object

Name	Type	Description
`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` object

To learn more about check runs and requested actions, see "Check runs and requested actions."

Name	Type	Description
`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.

Example of `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": ""
    }
}

Response

Status: 201 Created

{
  "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": "http://github.com/github/hello-world/runs/4",
  "details_url": "https://example.com",
  "status": "in_progress",
  "conclusion": null,
  "started_at": "2018-05-04T01:14:52Z",
  "completed_at": null,
  "output": {
    "title": "Mighty Readme Report",
    "summary": "",
    "text": ""
  },
  "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",
      "hooks_url": "https://api.github.com/orgs/github/hooks",
      "issues_url": "https://api.github.com/orgs/github/issues",
      "members_url": "https://api.github.com/orgs/github/members{/member}",
      "public_members_url": "https://api.github.com/orgs/github/public_members{/member}",
      "avatar_url": "https://github.com/images/error/octocat_happy.gif",
      "description": "A great organization"
    },
    "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"
        }
      }
    }
  ]
}

Example of `completed` conclusion

{
  "name": "mighty_readme",
  "head_sha": "ce587453ced02b1526dfb4cb910479d431683101",
  "status": "completed",
  "started_at": "2017-11-30T19:39:10Z",
  "conclusion": "success",
  "completed_at": "2017-11-30T19:49:10Z",
  "output": {
    "title": "Mighty Readme report",
    "summary": "There are 0 failures, 2 warnings, and 1 notices.",
    "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": [
      {
"path": "README.md",
        "annotation_level": "warning",
        "title": "Spell Checker",
        "message": "Check your spelling for 'banaas'.",
        "raw_details": "Do you mean 'bananas' or 'banana'?",
        "start_line": 2,
        "end_line": 2
      },
      {
"path": "README.md",
        "annotation_level": "warning",
        "title": "Spell Checker",
        "message": "Check your spelling for 'aples'",
        "raw_details": "Do you mean 'apples' or 'Naples'",
        "start_line": 4,
        "end_line": 4
      }
    ],
    "images": [
      {
        "alt": "Super bananas",
        "image_url": "http://example.com/images/42"
      }
    ]
  },
  "actions": [
    {
      "label": "Fix",
      "identifier": "fix_errors",
      "description": "Allow us to fix these errors for you"
    }
  ]
}

Response

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": "http://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",
      "hooks_url": "https://api.github.com/orgs/github/hooks",
      "issues_url": "https://api.github.com/orgs/github/issues",
      "members_url": "https://api.github.com/orgs/github/members{/member}",
      "public_members_url": "https://api.github.com/orgs/github/public_members{/member}",
      "avatar_url": "https://github.com/images/error/octocat_happy.gif",
      "description": "A great organization"
    },
    "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"
        }
      }
    }
  ]
}

Update a check run

application/vnd.github.antiope-preview+json

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

PATCH /repos/:owner/:repo/check-runs/:check_run_id

Parameters

Name	Type	Description
`name`	`string`	The name of the check. For example, "code-coverage".
`details_url`	`string`	The URL of the integrator's site that has the full details of the check.
`external_id`	`string`	A reference for the run on the integrator's system.
`started_at`	`string`	This is a timestamp in ISO 8601 format: `YYYY-MM-DDTHH:MM:SSZ`.
`status`	`string`	The current status. Can be one of `queued`, `in_progress`, or `completed`.
`conclusion`	`string`	Required if you provide `completed_at` or a `status` of `completed`. The final conclusion of the check. Can be one of `success`, `failure`, `neutral`, `cancelled`, `skipped`, `timed_out`, or `action_required`. Note: Providing `conclusion` will automatically set the `status` parameter to `completed`. Only GitHub can change a check run conclusion to `stale`.
`completed_at`	`string`	The time the check completed. This is a timestamp in ISO 8601 format: `YYYY-MM-DDTHH:MM:SSZ`.
`output`	`object`	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.
`actions`	`array of objects`	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.

`output` object

Name	Type	Description
`title`	`string`	Required.
`summary`	`text`	Required. Can contain Markdown.
`text`	`text`	Can contain Markdown.
`annotations`	`array of objects`	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.
`images`	`array of objects`	Adds images to the output displayed in the GitHub pull request UI. See the `images` object description for details.

`annotations` object

Name	Type	Description
`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.

`images` object

Name	Type	Description
`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` object

To learn more about check runs and requested actions, see "Check runs and requested actions."

Name	Type	Description
`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.

Example

{
  "name": "mighty_readme",
  "started_at": "2018-05-04T01:14:52Z",
  "status": "completed",
  "conclusion": "success",
  "completed_at": "2018-05-04T01:14:52Z",
  "output": {
    "title": "Mighty Readme report",
    "summary": "There are 0 failures, 2 warnings, and 1 notices.",
    "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": [
      {
"path": "README.md",
        "annotation_level": "warning",
        "title": "Spell Checker",
        "message": "Check your spelling for 'banaas'.",
        "raw_details": "Do you mean 'bananas' or 'banana'?",
        "start_line": 2,
        "end_line": 2
      },
      {
"path": "README.md",
        "annotation_level": "warning",
        "title": "Spell Checker",
        "message": "Check your spelling for 'aples'",
        "raw_details": "Do you mean 'apples' or 'Naples'",
        "start_line": 4,
        "end_line": 4
      }
    ],
    "images": [
      {
        "alt": "Super bananas",
        "image_url": "http://example.com/images/42"
      }
    ]
  }
}

Response

Status: 200 OK

{
  "id": 4,
  "head_sha": "ce587453ced02b1526dfb4cb910479d431683101",
  "node_id": "MDg6Q2hlY2tSdW40",
  "external_id": "",
  "url": "https://api.github.com/repos/github/hello-world/check-runs/4",
  "html_url": "http://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",
      "hooks_url": "https://api.github.com/orgs/github/hooks",
      "issues_url": "https://api.github.com/orgs/github/issues",
      "members_url": "https://api.github.com/orgs/github/members{/member}",
      "public_members_url": "https://api.github.com/orgs/github/public_members{/member}",
      "avatar_url": "https://github.com/images/error/octocat_happy.gif",
      "description": "A great organization"
    },
    "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"
        }
      }
    }
  ]
}

List check runs for a Git reference

application/vnd.github.antiope-preview+json

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.

GET /repos/:owner/:repo/commits/:ref/check-runs

Parameters

Name	Type	Description
`check_name`	`string`	Returns check runs with the specified `name`.
`status`	`string`	Returns check runs with the specified `status`. Can be one of `queued`, `in_progress`, or `completed`.
`filter`	`string`	Filters check runs by their `completed_at` timestamp. Can be one of `latest` (returning the most recent check runs) or `all`. Default: `latest`

Response

Status: 200 OK
Link: <https://api.github.com/resource?page=2>; rel="next",
      <https://api.github.com/resource?page=5>; rel="last"

{
  "total_count": 1,
  "check_runs": [
    {
      "id": 4,
      "head_sha": "ce587453ced02b1526dfb4cb910479d431683101",
      "node_id": "MDg6Q2hlY2tSdW40",
      "external_id": "",
      "url": "https://api.github.com/repos/github/hello-world/check-runs/4",
      "html_url": "http://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",
          "hooks_url": "https://api.github.com/orgs/github/hooks",
          "issues_url": "https://api.github.com/orgs/github/issues",
          "members_url": "https://api.github.com/orgs/github/members{/member}",
          "public_members_url": "https://api.github.com/orgs/github/public_members{/member}",
          "avatar_url": "https://github.com/images/error/octocat_happy.gif",
          "description": "A great organization"
        },
        "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"
            }
          }
        }
      ]
    }
  ]
}

List check runs in a check suite

application/vnd.github.antiope-preview+json

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.

GET /repos/:owner/:repo/check-suites/:check_suite_id/check-runs

Parameters

Name	Type	Description
`check_name`	`string`	Returns check runs with the specified `name`.
`status`	`string`	Returns check runs with the specified `status`. Can be one of `queued`, `in_progress`, or `completed`.
`filter`	`string`	Filters check runs by their `completed_at` timestamp. Can be one of `latest` (returning the most recent check runs) or `all`. Default: `latest`

Response

Status: 200 OK
Link: <https://api.github.com/resource?page=2>; rel="next",
      <https://api.github.com/resource?page=5>; rel="last"

{
  "total_count": 1,
  "check_runs": [
    {
      "id": 4,
      "head_sha": "ce587453ced02b1526dfb4cb910479d431683101",
      "node_id": "MDg6Q2hlY2tSdW40",
      "external_id": "",
      "url": "https://api.github.com/repos/github/hello-world/check-runs/4",
      "html_url": "http://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",
          "hooks_url": "https://api.github.com/orgs/github/hooks",
          "issues_url": "https://api.github.com/orgs/github/issues",
          "members_url": "https://api.github.com/orgs/github/members{/member}",
          "public_members_url": "https://api.github.com/orgs/github/public_members{/member}",
          "avatar_url": "https://github.com/images/error/octocat_happy.gif",
          "description": "A great organization"
        },
        "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"
            }
          }
        }
      ]
    }
  ]
}

Get a check run

application/vnd.github.antiope-preview+json

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.

GET /repos/:owner/:repo/check-runs/:check_run_id

Response

Status: 200 OK

{
  "id": 4,
  "head_sha": "ce587453ced02b1526dfb4cb910479d431683101",
  "node_id": "MDg6Q2hlY2tSdW40",
  "external_id": "",
  "url": "https://api.github.com/repos/github/hello-world/check-runs/4",
  "html_url": "http://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",
      "hooks_url": "https://api.github.com/orgs/github/hooks",
      "issues_url": "https://api.github.com/orgs/github/issues",
      "members_url": "https://api.github.com/orgs/github/members{/member}",
      "public_members_url": "https://api.github.com/orgs/github/public_members{/member}",
      "avatar_url": "https://github.com/images/error/octocat_happy.gif",
      "description": "A great organization"
    },
    "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"
        }
      }
    }
  ]
}

List check run annotations

application/vnd.github.antiope-preview+json

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.

GET /repos/:owner/:repo/check-runs/:check_run_id/annotations

Response

Status: 200 OK
Link: <https://api.github.com/resource?page=2>; rel="next",
      <https://api.github.com/resource?page=5>; rel="last"

[
  {
    "path": "README.md",
    "start_line": 2,
    "end_line": 2,
    "start_column": 5,
    "end_column": 10,
    "annotation_level": "warning",
    "title": "Spell Checker",
    "message": "Check your spelling for 'banaas'.",
    "raw_details": "Do you mean 'bananas' or 'banana'?"
  }
]

The content on this site may be out of date. For the most accurate and up-to-date content, visit docs.github.com. We've unified all of GitHub's product documentation in one place! Check out the new locations for REST API, GraphQL API, and Developers. Learn more on the GitHub blog.

Check Runs

Check runs and requested actions

Create a check run

Parameters

output object

annotations object

images object

actions object

Example of in_progress conclusion

Response

Example of completed conclusion

Response

Update a check run

Parameters

output object

annotations object

images object

actions object

Example

Response

List check runs for a Git reference

Parameters

Response

List check runs in a check suite

Parameters

Response

Get a check run

Response

List check run annotations

Response

The content on this site may be out of date. For the most accurate and up-to-date content, visit docs.github.com.

We've unified all of GitHub's product documentation in one place! Check out the new locations for REST API, GraphQL API, and Developers.
Learn more on the GitHub blog.

`output` object

`annotations` object

`images` object

`actions` object

Example of `in_progress` conclusion

Example of `completed` conclusion

`output` object

`annotations` object

`images` object

`actions` object