Skip to content
forgit api docs

List check runs for a Git reference

GET
/repos/{owner}/{repo}/commits/{ref}/check-runs

Lists check runs for a commit ref. The ref can be a SHA, branch name, or a tag name.

[!NOTE] The endpoints to manage checks only look 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.

If there are more than 1000 check suites on a single git reference, this endpoint will limit check runs to the 1000 most recent check suites. To iterate over all possible check runs, use the List check suites for a Git reference endpoint and provide the check_suite_id parameter to the List check runs in a check suite endpoint.

OAuth app tokens and personal access tokens (classic) need the repo scope to use this endpoint on a private repository.

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.

ref
required
string

The commit reference. Can be a commit SHA, branch name (heads/BRANCH_NAME), or tag name (tags/TAG_NAME). For more information, see “Git References” in the Git documentation.

Query Parameters

Section titled “ Query Parameters ”
check_name
string

Returns check runs with the specified name.

status
string
Allowed values: queued in_progress completed

Returns check runs with the specified status.

filter
string
default: latest
Allowed values: latest all

Filters check runs by their completed_at timestamp. latest returns the most recent check runs.

per_page
integer
default: 30

The number of results per page (max 100). For more information, see “Using pagination in the REST API.”

page
integer
default: 1

The page number of the results to fetch. For more information, see “Using pagination in the REST API.”

app_id
integer

Responses

Section titled “ Responses ”

200

Section titled “ 200 ”

Response

Media type application/json
object
total_count
required
integer
check_runs
required
Array<object>
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
Example default 
{
  "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": "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"
            }
          }
        }
      ]
    }
  ]
}

Headers

Section titled “ Headers ”
Link
string
Example 
<https://api.github.com/resource?page=2>; rel="next", <https://api.github.com/resource?page=5>; rel="last"