GitHub Checks API

openapi: 3.2.0
info:
  version: 1.1.4
  title: GitHub v3 REST Checks API
  description: GitHub's v3 REST API.
  license:
    name: MIT
    url: https://spdx.org/licenses/MIT
  termsOfService: https://docs.github.com/articles/github-terms-of-service
  contact:
    name: Support
    url: https://support.github.com/contact?tags=dotcom-rest-api
  x-github-plan: ghes
  x-github-release: 3.9
servers:
- url: '{protocol}://{hostname}/api/v3'
  variables:
    hostname:
      description: Self-hosted Enterprise Server hostname
      default: HOSTNAME
    protocol:
      description: Self-hosted Enterprise Server protocol
      default: http
tags:
- name: Checks
  description: Rich interactions with checks run by your integrations.
paths:
  /repos/{owner}/{repo}/check-runs:
    post:
      summary: GitHub Create a Check Run
      description: '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.'
      tags:
      - Checks
      operationId: checks/create
      externalDocs:
        description: API method documentation
        url: https://docs.github.com/enterprise-server@3.9/rest/checks/runs#create-a-check-run
      parameters:
      - $ref: '#/components/parameters/owner'
      - $ref: '#/components/parameters/repo'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  description: The name of the check. For example, "code-coverage".
                head_sha:
                  type: string
                  description: The SHA of the commit.
                details_url:
                  type: string
                  description: 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:
                  type: string
                  description: A reference for the run on the integrator's system.
                status:
                  type: string
                  description: The current status.
                  enum:
                  - queued
                  - in_progress
                  - completed
                  default: queued
                started_at:
                  type: string
                  format: date-time
                  description: 'The time that the check run began. This is a timestamp in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format: `YYYY-MM-DDTHH:MM:SSZ`.'
                conclusion:
                  type: string
                  description: "**Required if you provide `completed_at` or a `status` of `completed`**. The final conclusion of the check. \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
                completed_at:
                  type: string
                  format: date-time
                  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`.'
                output:
                  type: object
                  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.
                  properties:
                    title:
                      type: string
                      description: The title of the check run.
                    summary:
                      type: string
                      maxLength: 65535
                      description: 'The summary of the check run. This parameter supports Markdown. **Maximum length**: 65535 characters.'
                    text:
                      type: string
                      maxLength: 65535
                      description: 'The details of the check run. This parameter supports Markdown. **Maximum length**: 65535 characters.'
                    annotations:
                      type: array
                      description: 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](https://docs.github.com/enterprise-server@3.9/rest/checks/runs#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](https://docs.github.com/enterprise-server@3.9/articles/about-status-checks#checks)".
                      maxItems: 50
                      items:
                        type: object
                        properties:
                          path:
                            type: string
                            description: The path of the file to add an annotation to. For example, `assets/css/main.css`.
                          start_line:
                            type: integer
                            description: The start line of the annotation. Line numbers start at 1.
                          end_line:
                            type: integer
                            description: The end line of the annotation.
                          start_column:
                            type: integer
                            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. Column numbers start at 1.
                          end_column:
                            type: integer
                            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.
                          annotation_level:
                            type: string
                            description: The level of the annotation.
                            enum:
                            - notice
                            - warning
                            - failure
                          message:
                            type: string
                            description: A short description of the feedback for these lines of code. The maximum size is 64 KB.
                          title:
                            type: string
                            description: The title that represents the annotation. The maximum size is 255 characters.
                          raw_details:
                            type: string
                            description: Details about this annotation. The maximum size is 64 KB.
                        required:
                        - path
                        - start_line
                        - end_line
                        - annotation_level
                        - message
                    images:
                      type: array
                      description: Adds images to the output displayed in the GitHub pull request UI.
                      items:
                        type: object
                        properties:
                          alt:
                            type: string
                            description: The alternative text for the image.
                          image_url:
                            type: string
                            description: The full URL of the image.
                          caption:
                            type: string
                            description: A short image description.
                        required:
                        - alt
                        - image_url
                  required:
                  - title
                  - summary
                actions:
                  type: array
                  description: 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](https://docs.github.com/enterprise-server@3.9/webhooks/event-payloads/#check_run) 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](https://docs.github.com/enterprise-server@3.9/rest/guides/using-the-rest-api-to-interact-with-checks#check-runs-and-requested-actions)."
                  maxItems: 3
                  items:
                    type: object
                    properties:
                      label:
                        type: string
                        maxLength: 20
                        description: The text to be displayed on a button in the web UI. The maximum size is 20 characters.
                      description:
                        type: string
                        maxLength: 40
                        description: A short explanation of what this action would do. The maximum size is 40 characters.
                      identifier:
                        type: string
                        maxLength: 20
                        description: A reference for the action on the integrator's system. The maximum size is 20 characters.
                    required:
                    - label
                    - description
                    - identifier
              required:
              - name
              - head_sha
              oneOf:
              - properties:
                  status:
                    enum:
                    - completed
                required:
                - status
                - conclusion
                additionalProperties: true
              - properties:
                  status:
                    enum:
                    - queued
                    - in_progress
                additionalProperties: true
            examples:
              example-of-in-progress-conclusion:
                summary: Example of an in_progress conclusion
                value:
                  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: ''
              example-of-completed-conclusion:
                summary: Example of a completed conclusion
                value:
                  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
      responses:
        '201':
          description: Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/check-run'
              examples:
                example-of-completed-conclusion:
                  $ref: '#/components/examples/check-run-example-of-completed-conclusion'
                example-of-in-progress-conclusion:
                  $ref: '#/components/examples/check-run-example-of-in-progress-conclusion'
      x-github:
        githubCloudOnly: false
        enabledForGitHubApps: true
        category: checks
        subcategory: runs
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /repos/{owner}/{repo}/check-runs/{check_run_id}:
    get:
      summary: GitHub Get a Check Run
      description: 'Gets a single check run using its `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.


        OAuth app tokens and personal access tokens (classic) need the `repo` scope to use this endpoint on a private repository.'
      tags:
      - Checks
      operationId: checks/get
      externalDocs:
        description: API method documentation
        url: https://docs.github.com/enterprise-server@3.9/rest/checks/runs#get-a-check-run
      parameters:
      - $ref: '#/components/parameters/owner'
      - $ref: '#/components/parameters/repo'
      - $ref: '#/components/parameters/check-run-id'
      responses:
        '200':
          description: Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/check-run'
              examples:
                default:
                  $ref: '#/components/examples/check-run'
      x-github:
        githubCloudOnly: false
        enabledForGitHubApps: true
        category: checks
        subcategory: runs
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    patch:
      summary: GitHub Update a Check Run
      description: 'Updates a check run for a specific commit in a repository.


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


        OAuth apps and personal access tokens (classic) cannot use this endpoint.'
      tags:
      - Checks
      operationId: checks/update
      externalDocs:
        description: API method documentation
        url: https://docs.github.com/enterprise-server@3.9/rest/checks/runs#update-a-check-run
      parameters:
      - $ref: '#/components/parameters/owner'
      - $ref: '#/components/parameters/repo'
      - $ref: '#/components/parameters/check-run-id'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  description: The name of the check. For example, "code-coverage".
                details_url:
                  type: string
                  description: The URL of the integrator's site that has the full details of the check.
                external_id:
                  type: string
                  description: A reference for the run on the integrator's system.
                started_at:
                  type: string
                  format: date-time
                  description: 'This is a timestamp in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format: `YYYY-MM-DDTHH:MM:SSZ`.'
                status:
                  type: string
                  description: The current status.
                  enum:
                  - queued
                  - in_progress
                  - completed
                conclusion:
                  type: string
                  description: "**Required if you provide `completed_at` or a `status` of `completed`**. The final conclusion of the check. \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
                completed_at:
                  type: string
                  format: date-time
                  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`.'
                output:
                  type: object
                  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.
                  properties:
                    title:
                      type: string
                      description: '**Required**.'
                    summary:
                      type: string
                      description: Can contain Markdown.
                      maxLength: 65535
                    text:
                      type: string
                      description: Can contain Markdown.
                      maxLength: 65535
                    annotations:
                      type: array
                      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.9/rest/checks/runs#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 annotations in the UI, see "[About status checks](https://docs.github.com/enterprise-server@3.9/articles/about-status-checks#checks)".
                      maxItems: 50
                      items:
                        type: object
                        properties:
                          path:
                            type: string
                            description: The path of the file to add an annotation to. For example, `assets/css/main.css`.
                          start_line:
                            type: integer
                            description: The start line of the annotation. Line numbers start at 1.
                          end_line:
                            type: integer
                            description: The end line of the annotation.
                          start_column:
                            type: integer
                            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. Column numbers start at 1.
                          end_column:
                            type: integer
                            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.
                          annotation_level:
                            type: string
                            description: The level of the annotation.
                            enum:
                            - notice
                            - warning
                            - failure
                          message:
                            type: string
                            description: A short description of the feedback for these lines of code. The maximum size is 64 KB.
                          title:
                            type: string
                            description: The title that represents the annotation. The maximum size is 255 characters.
                          raw_details:
                            type: string
                            description: Details about this annotation. The maximum size is 64 KB.
                        required:
                        - path
                        - start_line
                        - end_line
                        - annotation_level
                        - message
                    images:
                      type: array
                      description: Adds images to the output displayed in the GitHub pull request UI.
                      items:
                        type: object
                        properties:
                          alt:
                            type: string
                            description: The alternative text for the image.
                          image_url:
                            type: string
                            description: The full URL of the image.
                          caption:
                            type: string
                            description: A short image description.
                        required:
                        - alt
                        - image_url
                  required:
                  - summary
                actions:
                  type: array
                  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. To learn more about check runs and requested actions, see "[Check runs and requested actions](https://docs.github.com/enterprise-server@3.9/rest/guides/using-the-rest-api-to-interact-with-checks#check-runs-and-requested-actions)."
                  maxItems: 3
                  items:
                    type: object
                    properties:
                      label:
                        type: string
                        maxLength: 20
                        description: The text to be displayed on a button in the web UI. The maximum size is 20 characters.
                      description:
                        type: string
                        maxLength: 40
                        description: A short explanation of what this action would do. The maximum size is 40 characters.
                      identifier:
                        type: string
                        maxLength: 20
                        description: A reference for the action on the integrator's system. The maximum size is 20 characters.
                    required:
                    - label
                    - description
                    - identifier
              anyOf:
              - properties:
                  status:
                    enum:
                    - completed
                required:
                - conclusion
                additionalProperties: true
              - properties:
                  status:
                    enum:
                    - queued
                    - in_progress
                additionalProperties: true
            examples:
              default:
                value:
                  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
      responses:
        '200':
          description: Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/check-run'
              examples:
                default:
                  $ref: '#/components/examples/check-run'
      x-github:
        githubCloudOnly: false
        enabledForGitHubApps: true
        category: checks
        subcategory: runs
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /repos/{owner}/{repo}/check-runs/{check_run_id}/annotations:
    get:
      summary: GitHub List Check Run Annotations
      description: 'Lists annotations for a check run using the annotation `id`.


        OAuth app tokens and personal access tokens (classic) need the `repo` scope to use this endpoint on a private repository.'
      tags:
      - Checks
      operationId: checks/list-annotations
      externalDocs:
        description: API method documentation
        url: https://docs.github.com/enterprise-server@3.9/rest/checks/runs#list-check-run-annotations
      parameters:
      - $ref: '#/components/parameters/owner'
      - $ref: '#/components/parameters/repo'
      - $ref: '#/components/parameters/check-run-id'
      - $ref: '#/components/parameters/per-page'
      - $ref: '#/components/parameters/page'
      responses:
        '200':
          description: Response
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/check-annotation'
              examples:
                default:
                  $ref: '#/components/examples/check-annotation-items'
          headers:
            Link:
              $ref: '#/components/headers/link'
      x-github:
        githubCloudOnly: false
        enabledForGitHubApps: true
        category: checks
        subcategory: runs
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /repos/{owner}/{repo}/check-runs/{check_run_id}/rerequest:
    post:
      summary: GitHub Rerequest a Check Run
      description: 'Triggers GitHub to rerequest an existing check run, without pushing new code to a repository. This endpoint will trigger the [`check_run` webhook](https://docs.github.com/enterprise-server@3.9/webhooks/event-payloads/#check_run) event with the action `rerequested`. When a check run is `rerequested`, its `status` is reset to `queued` and the `conclusion` is cleared.


        For more information about how to re-run GitHub Actions jobs, see "[Re-run a job from a workflow run](https://docs.github.com/enterprise-server@3.9/rest/actions/workflow-runs#re-run-a-job-from-a-workflow-run)".


        OAuth apps and personal access tokens (classic) cannot use this endpoint.'
      tags:
      - Checks
      operationId: checks/rerequest-run
      externalDocs:
        description: API method documentation
        url: https://docs.github.com/enterprise-server@3.9/rest/checks/runs#rerequest-a-check-run
      parameters:
      - $ref: '#/components/parameters/owner'
      - $ref: '#/components/parameters/repo'
      - $ref: '#/components/parameters/check-run-id'
      responses:
        '201':
          description: Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/empty-object'
              examples:
                default:
                  value: null
        '403':
          description: Forbidden if the check run is not rerequestable or doesn't belong to the authenticated GitHub App
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/basic-error'
        '404':
          $ref: '#/components/responses/not_found'
        '422':
          description: Validation error if the check run is not rerequestable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/basic-error'
      x-github:
        githubCloudOnly: false
        enabledForGitHubApps: true
        category: checks
        subcategory: runs
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /repos/{owner}/{repo}/check-suites:
    post:
      summary: GitHub Create a Check Suite
      description: 'Creates a check suite manually. By default, check suites are automatically created when you create a [check run](https://docs.github.com/enterprise-server@3.9/rest/checks/runs). You only need to use this endpoint for manually creating check suites when you''ve disabled automatic creation using "[Update repository preferences for check suites](https://docs.github.com/enterprise-server@3.9/rest/checks/suites#update-repository-preferences-for-check-suites)".


        **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 and a `null` value for `head_branch`.


        OAuth apps and personal access tokens (classic) cannot use this endpoint.'
      tags:
      - Checks
      operationId: checks/create-suite
      externalDocs:
        description: API method documentation
        url: https://docs.github.com/enterprise-server@3.9/rest/checks/suites#create-a-check-suite
      parameters:
      - $ref: '#/components/parameters/owner'
      - $ref: '#/components/parameters/repo'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                head_sha:
                  type: string
                  description: The sha of the head commit.
              required:
              - head_sha
            examples:
              default:
                value:
                  head_sha: d6fde92930d4715a2b49857d24b940956b26d2d3
      responses:
        '200':
          description: Response when the suite alre

# --- truncated at 32 KB (136 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/github/refs/heads/main/openapi/github-checks-api-openapi.yml