Merge pull request #712 from github/openapi-update-08649cd8792b9a3d7fd6ab452c396c7a873e3ed2c2d7e633d7a6630ca2de6377

Update OpenAPI Descriptions

Author: becco

descriptions/api.github.com/api.github.com.json

@@ -8460,6 +8460,8 @@ paths:
                         labels:
                           type: array
                           items:
+                            title: Self hosted runner label
+                            description: A label for a self hosted runner
                             type: object
                             properties:
                               id:
@@ -8475,6 +8477,8 @@ paths:
                                 enum:
                                 - read-only
                                 - custom
+                            required:
+                            - name
                       required: &89
                       - id
                       - name
@@ -12548,7 +12552,7 @@ paths:
                   description: The Markdown text to render in HTML.
                   type: string
                 mode:
-                  description: The rendering mode.
+                  description: The rendering mode. Can be either `markdown` or `gfm`.
                   enum:
                   - markdown
                   - gfm
@@ -12557,7 +12561,9 @@ paths:
                   type: string
                 context:
                   description: The repository context to use when creating references
-                    in `gfm` mode.
+                    in `gfm` mode.  For example, setting `context` to `octo-org/octo-repo`
+                    will change the text `#42` into an HTML link to issue 42 in the
+                    `octo-org/octo-repo` repository.
                   type: string
               required:
               - text
@@ -22904,9 +22910,11 @@ paths:
                       created_at: '2011-01-26T19:01:12Z'
                       updated_at: '2011-01-26T19:14:43Z'
                       permissions:
-                        admin: false
-                        push: false
                         pull: true
+                        triage: false
+                        push: false
+                        maintain: false
+                        admin: false
                       allow_rebase_merge: true
                       temp_clone_token: ABTLWHOULUVAXGTRYU7OC2876QJ2O
                       allow_squash_merge: true
@@ -30225,6 +30233,8 @@ paths:
                         enabled:
                           type: boolean
                         required_status_checks:
+                          title: Protected Branch Required Status Check
+                          description: Protected Branch Required Status Check
                           type: object
                           properties:
                             url:
@@ -31111,13 +31121,33 @@ paths:
                       description: Require branches to be up to date before merging.
                     contexts:
                       type: array
-                      description: The list of status checks to require in order to
-                        merge into this branch. If any of these checks have recently
-                        been set by a particular GitHub App, they will be required
-                        to come from that app in future for the branch to merge. Use
-                        `checks` instead of `contexts` for more fine-grained control.
+                      deprecated: true
+                      description: "**Deprecated**: The list of status checks to require
+                        in order to merge into this branch. If any of these checks
+                        have recently been set by a particular GitHub App, they will
+                        be required to come from that app in future for the branch
+                        to merge. Use `checks` instead of `contexts` for more fine-grained
+                        control.\n"
                       items:
                         type: string
+                    checks:
+                      type: array
+                      description: The list of status checks to require in order to
+                        merge into this branch.
+                      items:
+                        type: object
+                        required:
+                        - context
+                        properties:
+                          context:
+                            type: string
+                            description: The name of the required check
+                          app_id:
+                            type: integer
+                            description: The ID of the GitHub App that must provide
+                              this check. Omit this field to automatically select
+                              the GitHub App that has recently provided this check,
+                              or any app if it was not set by a GitHub App.
                   required:
                   - strict
                   - contexts
@@ -31219,6 +31249,12 @@ paths:
                   description: 'Requires all conversations on code to be resolved
                     before a pull request can be merged into a branch that matches
                     this rule. Set to `false` to disable. Default: `false`.'
+                contexts:
+                  type: array
+                  description: The list of status checks to require in order to merge
+                    into this branch.
+                  items:
+                    type: string
               required:
               - required_status_checks
               - enforce_admins
@@ -32069,7 +32105,7 @@ paths:
       operationId: repos/update-status-check-protection
       externalDocs:
         description: API method documentation
-        url: https://docs.github.com/[email protected]/rest/reference/repos#update-status-check-potection
+        url: https://docs.github.com/[email protected]/rest/reference/repos#update-status-check-protection
       parameters:
       - name: owner
         in: path
@@ -32097,6 +32133,7 @@ paths:
                   description: Require branches to be up to date before merging.
                 contexts:
                   type: array
+                  deprecated: true
                   description: The list of status checks to require in order to merge
                     into this branch
                   items:
@@ -34753,6 +34790,10 @@ paths:
                     type: integer
                   check_runs_url:
                     type: string
+                  rerequestable:
+                    type: boolean
+                  runs_rerequestable:
+                    type: boolean
                 required: &260
                 - id
                 - node_id
@@ -37010,7 +37051,11 @@ paths:
       description: |-
         This endpoint triggers [notifications](https://docs.github.com/en/github/managing-subscriptions-and-notifications-on-github/about-notifications). Creating content too quickly using this endpoint may result in secondary rate limiting. See "[Secondary rate limits](https://docs.github.com/[email protected]/rest/overview/resources-in-the-rest-api#secondary-rate-limits)" and "[Dealing with secondary rate limits](https://docs.github.com/[email protected]/rest/guides/best-practices-for-integrators#dealing-with-secondary-rate-limits)" for details.
 
-        For more information on permission levels, see "[Repository permission levels for an organization](https://help.github.com/en/github/setting-up-and-managing-organizations-and-teams/repository-permission-levels-for-an-organization#permission-levels-for-repositories-owned-by-an-organization)".
+        For more information on permission levels, see "[Repository permission levels for an organization](https://help.github.com/en/github/setting-up-and-managing-organizations-and-teams/repository-permission-levels-for-an-organization#permission-levels-for-repositories-owned-by-an-organization)". There are restrictions on which permissions can be granted to organization members when an organization base role is in place. In this case, the permission being given must be equal to or higher than the org base permission. Otherwise, the request will fail with:
+
+        ```
+        Cannot assign {member} permission of {role name}
+        ```
 
         Note that, if you choose not to pass any parameters, you'll need to set `Content-Length` to zero when calling out to this endpoint. For more information, see "[HTTP verbs](https://docs.github.com/[email protected]/rest/overview/resources-in-the-rest-api#http-verbs)."
 
@@ -42717,8 +42762,8 @@ paths:
                 state:
                   type: string
                   description: The state of the status. Can be one of `error`, `failure`,
-                    `inactive`, `in_progress`, `queued` `pending`, or `success`. **Note:**
-                    To use the `inactive` state, you must provide the [`application/vnd.github.ant-man-preview+json`](https://docs.github.com/[email protected]/rest/overview/api-previews#enhanced-deployments)
+                    `inactive`, `in_progress`, `queued`, `pending`, or `success`.
+                    **Note:** To use the `inactive` state, you must provide the [`application/vnd.github.ant-man-preview+json`](https://docs.github.com/[email protected]/rest/overview/api-previews#enhanced-deployments)
                     custom media type. When you set a transient deployment to `inactive`,
                     the deployment will be shown as `destroyed` in GitHub.
                   enum:
@@ -51112,7 +51157,8 @@ paths:
                     for the label, without the leading `#`.
                 description:
                   type: string
-                  description: A short description of the label.
+                  description: A short description of the label. Must be 100 characters
+                    or fewer.
               required:
               - name
             example:
@@ -51247,7 +51293,8 @@ paths:
                     for the label, without the leading `#`.
                 description:
                   type: string
-                  description: A short description of the label.
+                  description: A short description of the label. Must be 100 characters
+                    or fewer.
             example:
               new_name: 'bug :bug:'
               description: Small bug fix required
@@ -66804,9 +66851,11 @@ paths:
                       created_at: '2011-01-26T19:01:12Z'
                       updated_at: '2011-01-26T19:14:43Z'
                       permissions:
-                        admin: false
-                        push: false
                         pull: true
+                        triage: false
+                        push: false
+                        maintain: false
+                        admin: false
                       allow_rebase_merge: true
                       temp_clone_token: ABTLWHOULUVAXGTRYU7OC2876QJ2O
                       allow_squash_merge: true