GitHub Trees API

openapi: 3.2.0
info:
  version: 1.1.4
  title: github-repos-api Trees 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: Trees
paths:
  /repos/{owner}/{repo}/git/trees:
    post:
      summary: GitHub Create Tree
      description: 'The tree creation API accepts nested entries. If you specify both a tree and a nested path modifying that tree, this endpoint will overwrite the contents of the tree with the new path contents, and create a new tree structure.


        If you use this endpoint to add, delete, or modify the file contents in a tree, you will need to commit the tree and then update a branch to point to the commit. For more information see "[Create a commit](https://docs.github.com/enterprise-server@3.9/rest/git/commits#create-a-commit)" and "[Update a reference](https://docs.github.com/enterprise-server@3.9/rest/git/refs#update-a-reference)."


        Returns an error if you try to delete a file that does not exist.'
      tags:
      - Trees
      operationId: createTree
      externalDocs:
        description: API method documentation
        url: https://docs.github.com/enterprise-server@3.9/rest/git/trees#create-a-tree
      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:
                tree:
                  type: array
                  description: Objects (of `path`, `mode`, `type`, and `sha`) specifying a tree structure.
                  items:
                    type: object
                    properties:
                      path:
                        type: string
                        description: The file referenced in the tree.
                      mode:
                        type: string
                        description: The file mode; one of `100644` for file (blob), `100755` for executable (blob), `040000` for subdirectory (tree), `160000` for submodule (commit), or `120000` for a blob that specifies the path of a symlink.
                        enum:
                        - '100644'
                        - '100755'
                        - '040000'
                        - '160000'
                        - '120000'
                      type:
                        type: string
                        description: Either `blob`, `tree`, or `commit`.
                        enum:
                        - blob
                        - tree
                        - commit
                      sha:
                        type: string
                        description: 'The SHA1 checksum ID of the object in the tree. Also called `tree.sha`. If the value is `null` then the file will be deleted.


                          **Note:** Use either `tree.sha` or `content` to specify the contents of the entry. Using both `tree.sha` and `content` will return an error.'
                      content:
                        type: string
                        description: 'The content you want this file to have. GitHub will write this blob out and use that SHA for this entry. Use either this, or `tree.sha`.


                          **Note:** Use either `tree.sha` or `content` to specify the contents of the entry. Using both `tree.sha` and `content` will return an error.'
                base_tree:
                  type: string
                  description: 'The SHA1 of an existing Git tree object which will be used as the base for the new tree. If provided, a new Git tree object will be created from entries in the Git tree object pointed to by `base_tree` and entries defined in the `tree` parameter. Entries defined in the `tree` parameter will overwrite items from `base_tree` with the same `path`. If you''re creating new changes on a branch, then normally you''d set `base_tree` to the SHA1 of the Git tree object of the current latest commit on the branch you''re working on.

                    If not provided, GitHub will create a new Git tree object from only the entries defined in the `tree` parameter. If you create a new commit pointing to such a tree, then all files which were a part of the parent commit''s tree and were not defined in the `tree` parameter will be listed as deleted by the new commit.

                    '
              required:
              - tree
            examples:
              default:
                value:
                  base_tree: 9fb037999f264ba9a7fc6274d15fa3ae2ab98312
                  tree:
                  - path: file.rb
                    mode: '100644'
                    type: blob
                    sha: 44b4fc6d56897b048c772eb4087f854f46256132
      responses:
        '201':
          description: Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/git-tree'
              examples:
                default:
                  $ref: '#/components/examples/git-tree'
          headers:
            Location:
              example: https://api.github.com/repos/octocat/Hello-World/trees/cd8274d15fa3ae2ab983129fb037999f264ba9a7
              schema:
                type: string
        '403':
          $ref: '#/components/responses/forbidden'
        '404':
          $ref: '#/components/responses/not_found'
        '422':
          $ref: '#/components/responses/validation_failed'
      x-github:
        githubCloudOnly: false
        enabledForGitHubApps: true
        category: git
        subcategory: trees
      security:
      - bearerHttpAuthentication: []
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /repos/{owner}/{repo}/git/trees/{tree_sha}:
    get:
      summary: GitHub Get Tree
      description: 'Returns a single tree using the SHA1 value or ref name for that tree.


        If `truncated` is `true` in the response then the number of items in the `tree` array exceeded our maximum limit. If you need to fetch more items, use the non-recursive method of fetching trees, and fetch one sub-tree at a time.



        **Note**: The limit for the `tree` array is 100,000 entries with a maximum size of 7 MB when using the `recursive` parameter.'
      tags:
      - Trees
      operationId: getTree
      externalDocs:
        description: API method documentation
        url: https://docs.github.com/enterprise-server@3.9/rest/git/trees#get-a-tree
      parameters:
      - $ref: '#/components/parameters/owner'
      - $ref: '#/components/parameters/repo'
      - name: tree_sha
        description: The SHA1 value or ref (branch or tag) name of the tree.
        in: path
        required: true
        schema:
          type: string
        x-multi-segment: true
        example: abc123def456789012345678901234567890
      - name: recursive
        description: 'Setting this parameter to any value returns the objects or subtrees referenced by the tree specified in `:tree_sha`. For example, setting `recursive` to any of the following will enable returning objects or subtrees: `0`, `1`, `"true"`, and `"false"`. Omit this parameter to prevent recursively returning objects or subtrees.'
        in: query
        required: false
        schema:
          type: string
        example: example_value
      - 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/git-tree'
              examples:
                default-response:
                  $ref: '#/components/examples/git-tree-default-response'
                response-recursively-retrieving-a-tree:
                  $ref: '#/components/examples/git-tree-response-recursively-retrieving-a-tree'
        '404':
          $ref: '#/components/responses/not_found'
        '422':
          $ref: '#/components/responses/validation_failed'
      x-github:
        githubCloudOnly: false
        enabledForGitHubApps: true
        category: git
        subcategory: trees
      security:
      - bearerHttpAuthentication: []
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  examples:
    git-tree-response-recursively-retrieving-a-tree:
      summary: Response recursively retrieving a tree
      value:
        sha: fc6274d15fa3ae2ab983129fb037999f264ba9a7
        url: https://api.github.com/repos/octocat/Hello-World/trees/fc6274d15fa3ae2ab983129fb037999f264ba9a7
        tree:
        - path: subdir/file.txt
          mode: '100644'
          type: blob
          size: 132
          sha: 7c258a9869f33c1e1e1f74fbb32f07c86cb5a75b
          url: https://api.github.com/repos/octocat/Hello-World/git/7c258a9869f33c1e1e1f74fbb32f07c86cb5a75b
        truncated: false
    git-tree-default-response:
      summary: Default response
      value:
        sha: 9fb037999f264ba9a7fc6274d15fa3ae2ab98312
        url: https://api.github.com/repos/octocat/Hello-World/trees/9fb037999f264ba9a7fc6274d15fa3ae2ab98312
        tree:
        - path: file.rb
          mode: '100644'
          type: blob
          size: 30
          sha: 44b4fc6d56897b048c772eb4087f854f46256132
          url: https://api.github.com/repos/octocat/Hello-World/git/blobs/44b4fc6d56897b048c772eb4087f854f46256132
        - path: subdir
          mode: '040000'
          type: tree
          sha: f484d249c660418515fb01c2b9662073663c242e
          url: https://api.github.com/repos/octocat/Hello-World/git/blobs/f484d249c660418515fb01c2b9662073663c242e
        - path: exec_file
          mode: '100755'
          type: blob
          size: 75
          sha: 45b983be36b73c0788dc9cbcb76cbb80fc7bb057
          url: https://api.github.com/repos/octocat/Hello-World/git/blobs/45b983be36b73c0788dc9cbcb76cbb80fc7bb057
        truncated: false
    git-tree:
      value:
        sha: cd8274d15fa3ae2ab983129fb037999f264ba9a7
        url: https://api.github.com/repos/octocat/Hello-World/trees/cd8274d15fa3ae2ab983129fb037999f264ba9a7
        tree:
        - path: file.rb
          mode: '100644'
          type: blob
          size: 132
          sha: 7c258a9869f33c1e1e1f74fbb32f07c86cb5a75b
          url: https://api.github.com/repos/octocat/Hello-World/git/blobs/7c258a9869f33c1e1e1f74fbb32f07c86cb5a75b
        truncated: true
  responses:
    forbidden:
      description: Forbidden
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/basic-error'
    validation_failed:
      description: Validation failed, or the endpoint has been spammed.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/validation-error'
    not_found:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/basic-error'
  schemas:
    git-tree:
      title: Git Tree
      description: The hierarchy between files in a Git repository.
      type: object
      properties:
        sha:
          type: string
          example: abc123def456789012345678901234567890
        url:
          type: string
          format: uri
          example: https://api.github.com/repos/octocat/Hello-World
        truncated:
          type: boolean
          example: true
        tree:
          description: Objects specifying a tree structure
          type: array
          items:
            type: object
            properties:
              path:
                type: string
                example: test/file.rb
              mode:
                type: string
                example: '040000'
              type:
                type: string
                example: tree
              sha:
                type: string
                example: 23f6827669e43831def8a7ad935069c8bd418261
              size:
                type: integer
                example: 12
              url:
                type: string
                example: https://api.github.com/repos/owner-482f3203ecf01f67e9deb18e/BBB_Private_Repo/git/blobs/23f6827669e43831def8a7ad935069c8bd418261
          example:
          - path: file.rb
            mode: '100644'
            type: blob
            size: 30
            sha: 44b4fc6d56897b048c772eb4087f854f46256132
            url: https://api.github.com/repos/octocat/Hello-World/git/blobs/44b4fc6d56897b048c772eb4087f854f46256132
            properties:
              path:
                type: string
              mode:
                type: string
              type:
                type: string
              size:
                type: integer
              sha:
                type: string
              url:
                type: string
            required:
            - path
            - mode
            - type
            - sha
            - url
            - size
      required:
      - sha
      - url
      - tree
      - truncated
    validation-error:
      title: Validation Error
      description: Validation Error
      type: object
      required:
      - message
      - documentation_url
      properties:
        message:
          type: string
          example: Example body text
        documentation_url:
          type: string
          example: https://api.github.com/repos/octocat/Hello-World
        errors:
          type: array
          items:
            type: object
            required:
            - code
            properties:
              resource:
                type: string
              field:
                type: string
              message:
                type: string
              code:
                type: string
              index:
                type: integer
              value:
                oneOf:
                - type: string
                - type: integer
                - type: array
                  items:
                    type: string
    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
  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/