GitHub Static Analysis Results Interchange Format API

openapi: 3.2.0
info:
  version: 1.1.4
  title: github-repos-api Static Analysis Results Interchange Format API
  description: 'Use the REST API to create, manage and control the workflow of public and

    private GitHub repositories.'
  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
servers:
- url: '{protocol}://{hostname}'
  variables:
    hostname:
      description: Self-hosted Enterprise Server hostname
      default: api.github.com
    protocol:
      description: Self-hosted Enterprise Server protocol
      default: https
tags:
- name: Static Analysis Results Interchange Format
paths:
  /repos/{owner}/{repo}/code-scanning/sarifs:
    post:
      summary: GitHub Upload an Analysis as Sarif Data
      description: "Uploads SARIF data containing the results of a code scanning analysis to make the results available in a repository. For troubleshooting information, see \"[Troubleshooting SARIF uploads](https://docs.github.com/enterprise-server@3.9/code-security/code-scanning/troubleshooting-sarif).\"\n\nThere are two places where you can upload code scanning results.\n - If you upload to a pull request, for example `--ref refs/pull/42/merge` or `--ref refs/pull/42/head`, then the results appear as alerts in a pull request check. For more information, see \"[Triaging code scanning alerts in pull requests](/code-security/secure-coding/triaging-code-scanning-alerts-in-pull-requests).\"\n - If you upload to a branch, for example `--ref refs/heads/my-branch`, then the results appear in the **Security** tab for your repository. For more information, see \"[Managing code scanning alerts for your repository](/code-security/secure-coding/managing-code-scanning-alerts-for-your-repository#viewing-the-alerts-for-a-repository).\"\n\nYou must compress the SARIF-formatted analysis data that you want to upload, using `gzip`, and then encode it as a Base64 format string. For example:\n\n```\ngzip -c analysis-data.sarif | base64 -w0\n```\n\nSARIF upload supports a maximum number of entries per the following data objects, and an analysis will be rejected if any of these objects is above its maximum value. For some objects, there are additional values over which the entries will be ignored while keeping the most important entries whenever applicable.\nTo get the most out of your analysis when it includes data above the supported limits, try to optimize the analysis configuration. For example, for the CodeQL tool, identify and remove the most noisy queries. For more information, see \"[SARIF results exceed one or more limits](https://docs.github.com/enterprise-server@3.9/code-security/code-scanning/troubleshooting-sarif/results-exceed-limit).\"\n\n\n| **SARIF data**                   | **Maximum values** | **Additional limits**                                                            |\n|-|::|-|\n| Runs per file                    |         20         |                                                                                  |\n| Results per run                  |       25,000       | Only the top 5,000 results will be included, prioritized by severity.            |\n| Rules per run                    |       25,000       |                                                                                  |\n| Tool extensions per run          |        100         |                                                                                  |\n| Thread Flow Locations per result |       10,000       | Only the top 1,000 Thread Flow Locations will be included, using prioritization. |\n| Location per result\t             |       1,000        | Only 100 locations will be included.                                             |\n| Tags per rule\t                   |         20         | Only 10 tags will be included.                                                   |\n\n\nThe `202 Accepted` response includes an `id` value.\nYou can use this ID to check the status of the upload by using it in the `/sarifs/{sarif_id}` endpoint.\nFor more information, see \"[Get information about a SARIF upload](/rest/code-scanning/code-scanning#get-information-about-a-sarif-upload).\"\n\nOAuth app tokens and personal access tokens (classic) need the `security_events` scope to use this endpoint with private or public repositories, or the `public_repo` scope to use this endpoint with only public repositories."
      operationId: uploadAnAnalysisAsSarifData
      tags:
      - Static Analysis Results Interchange Format
      externalDocs:
        description: API method documentation
        url: https://docs.github.com/enterprise-server@3.9/rest/code-scanning/code-scanning#upload-an-analysis-as-sarif-data
      parameters:
      - $ref: '#/components/parameters/owner'
      - $ref: '#/components/parameters/repo'
      - in: header
        name: Authorization
        schema:
          type: string
        example: example_value
      - in: header
        name: X-GitHub-Api-Version
        schema:
          type: string
          default: '2022-11-28'
        example: example_value
      - in: header
        name: Accept
        schema:
          type: string
          default: application/vnd.github+json
        example: example_value
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                commit_sha:
                  $ref: '#/components/schemas/code-scanning-analysis-commit-sha'
                ref:
                  $ref: '#/components/schemas/code-scanning-ref-full'
                sarif:
                  $ref: '#/components/schemas/code-scanning-analysis-sarif-file'
                checkout_uri:
                  description: 'The base directory used in the analysis, as it appears in the SARIF file.

                    This property is used to convert file paths from absolute to relative, so that alerts can be mapped to their correct location in the repository.'
                  example: file:///github/workspace/
                  type: string
                  format: uri
                started_at:
                  description: 'The time that the analysis run began. 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
                tool_name:
                  description: The name of the tool used to generate the code scanning analysis. If this parameter is not used, the tool name defaults to "API". If the uploaded SARIF contains a tool GUID, this will be available for filtering using the `tool_guid` parameter of operations such as `GET /repos/{owner}/{repo}/code-scanning/alerts`.
                  type: string
              additionalProperties: false
              required:
              - commit_sha
              - ref
              - sarif
            examples:
              default:
                value:
                  commit_sha: 4b6472266afd7b471e86085a6659e8c7f2b119da
                  ref: refs/heads/master
                  sarif: H4sICMLGdF4AA2V4YW1wbGUuc2FyaWYAvVjdbts2FL7PUxDCijaA/CM7iRNfLkPXYgHSNstumlzQ0pHFVCI1korjFgH2ONtr7Ul2KFmy/mOn6QIkjsjDw0/nfN85NL8dEGL9pNwAImqRObECrWM1H40kXQ2XTAfJIlEgXcE1cD10RTQSVDE10K4aKSqZP1AxuKOIKg1ydJU60jSfSh8Hk6EzHA/vlOCWbfa7B6kYPpj90rlsWCZcmbHP5Bs+4oAWIjQD2SMOeJLh2vIQDnIaQerqXHjw8YIgxohybxAyDsS4cAPKsp03K4RcUs6+Up2D+JXpd8mibKIQN9fM/aMCdbyBujGSSQgVxJtx5qX2d2qUcIweQhEuDQf3GBO6CKHkogx/N3MVCKl/AeVKFuf4y5ubsMGDTj1ep+5I7sgmLIpxtU38hLtmMRGSuCFVyip5eKzs5ydh+LztVL6f2m6oih1BkYiuyQIIJWodxVpERPj4sEiWBNNH8EWT0DMG8EAjzKVHXCrB4FkPu/F64NMk1OeC+2yZSNoBOoR7CC0EzYWGbm+xFDFIzbI011+cLjfZtyJkmMZfumAh02uL3NpV2y+MZ6RAjxibyKrNxxJcVjANSb4eBGwZ1M0KsuyR2poLr5rMl8vaDSeVn6eTWEO2j2xIEcmhwlTKNOi4GMOI8gfuZYkvJ7b4v5Tiumyz7RnHeodFzpS8ASIZCH/AYdWi2z3sG8JtFxJ6fF9yR9CdifBr9Pd6d5V2+zbJKjjCFGGmsHuYFy2ytJq9tUxcLSRSQecppOGKrpUxYfxefMEFK+wOGa4hudQByBVT0L+EKtyACxnRsABhEx1QjVDs1KNI9MbpnhqfE45B6FJvu3hRu5VRU9MhZLmK7fqkKyQSTHNoyMqUFMqXCV3CwAeqEwmVokraK8IuBaGvHjQ0gMYrKjnjyw7uk9uD8tgmsBbFMPnU1bV2ZhkJNkuolUiWys3UPWzs5aaIUz9TBe8zMb+6+nT+6fLy91dlE3xzeDDT4zYszb0bW6NjJd0Rvn2EnLvWLFSdKPpBzInzfRgu8ETyMcH8nIfMnJCeC2PyfTA+UKngcnGH7Hw2hGkVQs5YlIRCtdWZYQ4/73es2JlxkfViOEIhoWJq5Oo6UBBfiKIqFBWhiE3jJGbFwVoxBHTRSuIS67sMeplei24X20shLjG+8gqbKC/bESiNMC+wd5q5id0yeS7CJEqXzmrTWNq3k05l84P6f4/bEmXFJjI0fIt1BGQssUnUDkBYeVhE5TqPnMH3jqogDcP0zKcTgLPTMSzOjhbjuVOmW23l1fYNStulfo6sXlFsGLhbDy5RECPRYGCTgOj2bd4nUQEivEd0H7KKYxqnEhFohuur3a3UPskbH/+Yg0+M5P2MHRJu3ziHh3Z2NCrWt3XF1rWTw8Ne/pfbWYXnDSE0SNZQQt1i18q7te2vOhu7ehWuvVyeu0wbLZi24mhoo6aOOTltzG/lgdVvVoXQq5V+pewkFIzL8fjEcadT55jOjpzFzHuOTtDNrMkJPMVQDd7F09RID72O/UPZ0tmctqZ7kWX6EmSZnDpP8GU67SXM8XE3YSrxbKsx6UReZ4y6n/FVZfJjs9Z7stma75W5yQtkzjk5eSJxk1lv4o7+j8TlhaJ2lsKWZO6lruDPBLib3x5ZN/KGWzZ+pn///evv7OOf4iIBv3oY9L/l1wiJ9p0Tc+F1zZnOE9NxXWEus6IQhr5pMfoqxi8WPsuu0azsns4UC6WzNzHIzbeEx4P/AJ3SefgcFAAA
      responses:
        '202':
          description: Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/code-scanning-sarifs-receipt'
              examples:
                default:
                  $ref: '#/components/examples/code-scanning-sarif-upload'
        '400':
          description: Bad Request if the sarif field is invalid
        '403':
          $ref: '#/components/responses/code_scanning_forbidden_write'
        '404':
          $ref: '#/components/responses/not_found'
        '413':
          description: Payload Too Large if the sarif field is too large
        '503':
          $ref: '#/components/responses/service_unavailable'
      x-github:
        enabledForGitHubApps: true
        githubCloudOnly: false
        category: code-scanning
        subcategory: code-scanning
      security:
      - bearerHttpAuthentication: []
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /repos/{owner}/{repo}/code-scanning/sarifs/{sarif_id}:
    get:
      summary: GitHub Get Information About Sarif Upload
      description: 'Gets information about a SARIF upload, including the status and the URL of the analysis that was uploaded so that you can retrieve details of the analysis. For more information, see "[Get code scanning analysis for a repository](/rest/code-scanning/code-scanning#get-a-code-scanning-analysis-for-a-repository)."

        OAuth app tokens and personal access tokens (classic) need the `security_events` scope to use this endpoint with private or public repositories, or the `public_repo` scope to use this endpoint with only public repositories.'
      operationId: getInformationAboutSarifUpload
      tags:
      - Static Analysis Results Interchange Format
      externalDocs:
        description: API method documentation
        url: https://docs.github.com/enterprise-server@3.9/rest/code-scanning/code-scanning#get-information-about-a-sarif-upload
      parameters:
      - $ref: '#/components/parameters/owner'
      - $ref: '#/components/parameters/repo'
      - name: sarif_id
        description: The SARIF ID obtained after uploading.
        in: path
        schema:
          type: string
        required: true
        example: '12345678'
      - in: header
        name: Authorization
        schema:
          type: string
        example: example_value
      - in: header
        name: X-GitHub-Api-Version
        schema:
          type: string
          default: '2022-11-28'
        example: example_value
      - in: header
        name: Accept
        schema:
          type: string
          default: application/vnd.github+json
        example: example_value
      responses:
        '200':
          description: Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/code-scanning-sarifs-status'
              examples:
                default:
                  $ref: '#/components/examples/code-scanning-sarif-upload-status'
        '403':
          $ref: '#/components/responses/code_scanning_forbidden_read'
        '404':
          description: Not Found if the sarif id does not match any upload
        '503':
          $ref: '#/components/responses/service_unavailable'
      x-github:
        enabledForGitHubApps: true
        githubCloudOnly: false
        category: code-scanning
        subcategory: code-scanning
      security:
      - bearerHttpAuthentication: []
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  schemas:
    code-scanning-ref-full:
      type: string
      description: 'The full Git reference, formatted as `refs/heads/<branch name>`,

        `refs/tags/<tag>`, `refs/pull/<number>/merge`, or `refs/pull/<number>/head`.'
      pattern: ^refs/(heads|tags|pull)/.*$
      example: refs/heads/main
    code-scanning-analysis-commit-sha:
      description: The SHA of the commit to which the analysis you are uploading relates.
      type: string
      minLength: 40
      maxLength: 40
      pattern: ^[0-9a-fA-F]+$
    code-scanning-analysis-sarif-id:
      type: string
      description: An identifier for the upload.
      example: 6c81cd8e-b078-4ac3-a3be-1dad7dbd0b53
    basic-error:
      title: Basic Error
      description: Basic Error
      type: object
      properties:
        message:
          type: string
          example: Example body text
        documentation_url:
          type: string
          example: https://api.github.com/repos/octocat/Hello-World
        url:
          type: string
          example: https://api.github.com/repos/octocat/Hello-World
        status:
          type: string
          example: open
    code-scanning-sarifs-receipt:
      type: object
      properties:
        id:
          $ref: '#/components/schemas/code-scanning-analysis-sarif-id'
        url:
          type: string
          description: The REST API URL for checking the status of the upload.
          format: uri
          readOnly: true
          example: https://api.github.com/repos/octocat/Hello-World
    code-scanning-sarifs-status:
      type: object
      properties:
        processing_status:
          type: string
          enum:
          - pending
          - complete
          - failed
          description: '`pending` files have not yet been processed, while `complete` means results from the SARIF have been stored. `failed` files have either not been processed at all, or could only be partially processed.'
          example: pending
        analyses_url:
          type: string
          description: The REST API URL for getting the analyses associated with the upload.
          format: uri
          readOnly: true
          example: https://api.github.com/repos/octocat/Hello-World
        errors:
          type: array
          items:
            type: string
          description: Any errors that ocurred during processing of the delivery.
          readOnly: true
    code-scanning-analysis-sarif-file:
      description: Base64 string representing the SARIF file to upload. You must first compress your SARIF file using [`gzip`](http://www.gnu.org/software/gzip/manual/gzip.html) and then translate the contents of the file into a Base64 encoding string. For more information, see "[SARIF support for code scanning](https://docs.github.com/enterprise-server@3.9/code-security/secure-coding/sarif-support-for-code-scanning)."
      type: string
  responses:
    service_unavailable:
      description: Service unavailable
      content:
        application/json:
          schema:
            type: object
            properties:
              code:
                type: string
              message:
                type: string
              documentation_url:
                type: string
    not_found:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/basic-error'
    code_scanning_forbidden_read:
      description: Response if GitHub Advanced Security is not enabled for this repository
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/basic-error'
    code_scanning_forbidden_write:
      description: Response if the repository is archived or if GitHub Advanced Security is not enabled for this repository
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/basic-error'
  examples:
    code-scanning-sarif-upload-status:
      summary: Default response
      value:
        processing_status: complete
        analyses_url: https://api.github.com/repos/octocat/hello-world/code-scanning/analyses?sarif_id=47177e22-5596-11eb-80a1-c1e54ef945c6
    code-scanning-sarif-upload:
      summary: Default response
      value:
        id: 47177e22-5596-11eb-80a1-c1e54ef945c6
        url: https://api.github.com/repos/octocat/hello-world/code-scanning/sarifs/47177e22-5596-11eb-80a1-c1e54ef945c6
  parameters:
    owner:
      name: owner
      description: The account owner of the repository. The name is not case sensitive.
      in: path
      required: true
      schema:
        type: string
    repo:
      name: repo
      description: The name of the repository without the `.git` extension. The name is not case sensitive.
      in: path
      required: true
      schema:
        type: string
  securitySchemes:
    bearerHttpAuthentication:
      description: Bearer Token
      type: http
      scheme: Bearer
externalDocs:
  description: GitHub Enterprise Developer Docs
  url: https://docs.github.com/enterprise-server@3.9/rest/