# Update a check run

From **GitHub v3 REST API**.

`PATCH /repos/{owner}/{repo}/check-runs/{check_run_id}`

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

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

## Parameters

### `owner`

- Location: path
- Required: true
- Type: `string`

### `repo`

- Location: path
- Required: true
- Type: `string`

### `check_run_id`

- Location: path
- Required: true
- Type: `integer`

check_run_id parameter

## Request body

- Required: true
### `application/json`

- Type: `object`

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

```json
{"anyOf":[{"additionalProperties":true,"properties":{"status":{"enum":["completed"]}},"required":["conclusion"]},{"additionalProperties":true,"properties":{"status":{"enum":["queued","in_progress"]}}}],"properties":{"actions":{"description":"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](https://docs.github.com/enterprise-server@3.0/rest/reference/checks#actions-object) description. To learn more about check runs and requested actions, see \"[Check runs and requested actions](https://docs.github.com/enterprise-server@3.0/rest/reference/checks#check-runs-and-requested-actions).\"","items":{"properties":{"description":{"description":"A short explanation of what this action would do. The maximum size is 40 characters.","maxLength":40,"type":"string"},"identifier":{"description":"A reference for the action on the integrator's system. The maximum size is 20 characters.","maxLength":20,"type":"string"},"label":{"description":"The text to be displayed on a button in the web UI. The maximum size is 20 characters.","maxLength":20,"type":"string"}},"required":["label","description","identifier"],"type":"object"},"maxItems":3,"type":"array"},"completed_at":{"description":"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","type":"string"},"conclusion":{"description":"**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`.  \n**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.","enum":["action_required","cancelled","failure","neutral","success","skipped","stale","timed_out"],"type":"string"},"details_url":{"description":"The URL of the integrator's site that has the full details of the check.","type":"string"},"external_id":{"description":"A reference for the run on the integrator's system.","type":"string"},"name":{"description":"The name of the check. For example, \"code-coverage\".","type":"string"},"output":{"description":"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](https://docs.github.com/enterprise-server@3.0/rest/reference/checks#output-object-1) description.","properties":{"annotations":{"description":"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](https://docs.github.com/enterprise-server@3.0/rest/reference/checks#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](https://docs.github.com/articles/about-status-checks#checks)\". See the [`annotations` object](https://docs.github.com/enterprise-server@3.0/rest/reference/checks#annotations-object-1) description for details.","items":{"properties":{"annotation_level":{"description":"The level of the annotation. Can be one of `notice`, `warning`, or `failure`.","enum":["notice","warning","failure"],"type":"string"},"end_column":{"description":"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.","type":"integer"},"end_line":{"description":"The end line of the annotation.","type":"integer"},"message":{"description":"A short description of the feedback for these lines of code. The maximum size is 64 KB.","type":"string"},"path":{"description":"The path of the file to add an annotation to. For example, `assets/css/main.css`.","type":"string"},"raw_details":{"description":"Details about this annotation. The maximum size is 64 KB.","type":"string"},"start_column":{"description":"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.","type":"integer"},"start_line":{"description":"The start line of the annotation.","type":"integer"},"title":{"description":"The title that represents the annotation. The maximum size is 255 characters.","type":"string"}},"required":["path","start_line","end_line","annotation_level","message"],"type":"object"},"maxItems":50,"type":"array"},"images":{"description":"Adds images to the output displayed in the GitHub pull request UI. See the [`images` object](https://docs.github.com/enterprise-server@3.0/rest/reference/checks#annotations-object-1) description for details.","items":{"properties":{"alt":{"description":"The alternative text for the image.","type":"string"},"caption":{"description":"A short image description.","type":"string"},"image_url":{"description":"The full URL of the image.","type":"string"}},"required":["alt","image_url"],"type":"object"},"type":"array"},"summary":{"description":"Can contain Markdown.","maxLength":65535,"type":"string"},"text":{"description":"Can contain Markdown.","maxLength":65535,"type":"string"},"title":{"description":"**Required**.","type":"string"}},"required":["summary"],"type":"object"},"started_at":{"description":"This is a timestamp in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format: `YYYY-MM-DDTHH:MM:SSZ`.","format":"date-time","type":"string"},"status":{"description":"The current status. Can be one of `queued`, `in_progress`, or `completed`.","enum":["queued","in_progress","completed"],"type":"string"}},"type":"object"}
```

## Responses

### `200`

Response

### `application/json`

- Type: `object`

A check performed on the code of a given code change

```json
{
  "app": {
    "created_at": "2017-07-08T16:18:44-04:00",
    "description": "",
    "events": [
      "push",
      "pull_request"
    ],
    "external_url": "https://example.com",
    "html_url": "https://github.com/apps/octoapp",
    "id": 1,
    "name": "Octocat App",
    "node_id": "MDExOkludGVncmF0aW9uMQ==",
    "owner": {
      "avatar_url": "https://github.com/images/error/octocat_happy.gif",
      "events_url": "https://api.github.com/orgs/github/events",
      "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}",
      "gravatar_id": "",
      "html_url": "https://github.com/octocat",
      "id": 1,
      "login": "github",
      "node_id": "MDEyOk9yZ2FuaXphdGlvbjE=",
      "organizations_url": "https://api.github.com/users/octocat/orgs",
      "received_events_url": "https://api.github.com/users/octocat/received_events",
      "repos_url": "https://api.github.com/orgs/github/repos",
      "site_admin": true,
      "starred_url": "https://api.github.com/users/octocat/starred{/owner}{/repo}",
      "subscriptions_url": "https://api.github.com/users/octocat/subscriptions",
      "type": "User",
      "url": "https://api.github.com/orgs/github"
    },
    "permissions": {
      "contents": "read",
      "issues": "write",
      "metadata": "read",
      "single_file": "write"
    },
    "slug": "octoapp",
    "updated_at": "2017-07-08T16:18:44-04:00"
  },
  "check_suite": {
    "id": 5
  },
  "completed_at": "2018-05-04T01:14:52Z",
  "conclusion": "neutral",
  "details_url": "https://example.com",
  "external_id": "",
  "head_sha": "ce587453ced02b1526dfb4cb910479d431683101",
  "html_url": "https://github.com/github/hello-world/runs/4",
  "id": 4,
  "name": "mighty_readme",
  "node_id": "MDg6Q2hlY2tSdW40",
  "output": {
    "annotations_count": 2,
    "annotations_url": "https://api.github.com/repos/github/hello-world/check-runs/4/annotations",
    "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.",
    "title": "Mighty Readme report"
  },
  "pull_requests": [
    {
      "base": {
        "ref": "master",
        "repo": {
          "id": 526,
          "name": "hello-world",
          "url": "https://api.github.com/repos/github/hello-world"
        },
        "sha": "e7fdf7640066d71ad16a86fbcbb9c6a10a18af4f"
      },
      "head": {
        "ref": "say-hello",
        "repo": {
          "id": 526,
          "name": "hello-world",
          "url": "https://api.github.com/repos/github/hello-world"
        },
        "sha": "3dca65fa3e8d4b3da3f3d056c59aee1c50f41390"
      },
      "id": 1934,
      "number": 3956,
      "url": "https://api.github.com/repos/github/hello-world/pulls/1"
    }
  ],
  "started_at": "2018-05-04T01:14:52Z",
  "status": "completed",
  "url": "https://api.github.com/repos/github/hello-world/check-runs/4"
}
```

```json
{"description":"A check performed on the code of a given code change","properties":{"app":{"$ref":"#/components/schemas/nullable-integration"},"check_suite":{"nullable":true,"properties":{"id":{"type":"integer"}},"required":["id"],"type":"object"},"completed_at":{"example":"2018-05-04T01:14:52Z","format":"date-time","nullable":true,"type":"string"},"conclusion":{"enum":["success","failure","neutral","cancelled","skipped","timed_out","action_required"],"example":"neutral","nullable":true,"type":"string"},"deployment":{"$ref":"#/components/schemas/deployment-simple"},"details_url":{"example":"https://example.com","nullable":true,"type":"string"},"external_id":{"example":"42","nullable":true,"type":"string"},"head_sha":{"description":"The SHA of the commit that is being checked.","example":"009b8a3a9ccbb128af87f9b1c0f4c62e8a304f6d","type":"string"},"html_url":{"example":"https://github.com/github/hello-world/runs/4","nullable":true,"type":"string"},"id":{"description":"The id of the check.","example":21,"type":"integer"},"name":{"description":"The name of the check.","example":"test-coverage","type":"string"},"node_id":{"example":"MDg6Q2hlY2tSdW40","type":"string"},"output":{"properties":{"annotations_count":{"type":"integer"},"annotations_url":{"format":"uri","type":"string"},"summary":{"nullable":true,"type":"string"},"text":{"nullable":true,"type":"string"},"title":{"nullable":true,"type":"string"}},"required":["title","summary","text","annotations_count","annotations_url"],"type":"object"},"pull_requests":{"items":{"$ref":"#/components/schemas/pull-request-minimal"},"type":"array"},"started_at":{"example":"2018-05-04T01:14:52Z","format":"date-time","nullable":true,"type":"string"},"status":{"description":"The phase of the lifecycle that the check is currently in.","enum":["queued","in_progress","completed"],"example":"queued","type":"string"},"url":{"example":"https://api.github.com/repos/github/hello-world/check-runs/4","type":"string"}},"required":["id","node_id","head_sha","name","url","html_url","details_url","status","conclusion","started_at","completed_at","external_id","check_suite","output","app","pull_requests"],"title":"CheckRun","type":"object"}
```

## Request examples

### cURL

```shell
curl --request PATCH \
  --url {protocol}://{hostname}/api/v3/repos/{owner}/{repo}/check-runs/{check_run_id} \
  --header 'content-type: application/json' \
  --data '{
  "completed_at": "2018-05-04T01:14:52Z",
  "conclusion": "success",
  "name": "mighty_readme",
  "output": {
    "annotations": [
      {
        "annotation_level": "warning",
        "end_line": 2,
        "message": "Check your spelling for '\''banaas'\''.",
        "path": "README.md",
        "raw_details": "Do you mean '\''bananas'\'' or '\''banana'\''?",
        "start_line": 2,
        "title": "Spell Checker"
      },
      {
        "annotation_level": "warning",
        "end_line": 4,
        "message": "Check your spelling for '\''aples'\''",
        "path": "README.md",
        "raw_details": "Do you mean '\''apples'\'' or '\''Naples'\''",
        "start_line": 4,
        "title": "Spell Checker"
      }
    ],
    "images": [
      {
        "alt": "Super bananas",
        "image_url": "http://example.com/images/42"
      }
    ],
    "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.",
    "title": "Mighty Readme report"
  },
  "started_at": "2018-05-04T01:14:52Z",
  "status": "completed"
}'
```