fix: update docs to reflect new request parameters in 3 APIs and upda…

…ted API descriptions (#541)

WIP octokit/openapi updated

docs/apps/createInstallationAccessToken.md

@@ -68,11 +68,6 @@ The level of permission to grant the access token for checks on code.
 
 The level of permission to grant the access token for repository contents, commits, branches, downloads, releases, and merges.
 
-</td></tr>
-<tr><td>permissions.organization_custom_roles</td><td>no</td><td>
-
-The level of permission to grant the access token for custom roles management.
-
 </td></tr>
 <tr><td>permissions.deployments</td><td>no</td><td>
 
@@ -163,6 +158,11 @@ The level of permission to grant the access token for organization teams and mem
 
 The level of permission to grant the access token to manage access to an organization.
 
+</td></tr>
+<tr><td>permissions.organization_custom_roles</td><td>no</td><td>
+
+The level of permission to grant the access token for custom roles management. This property is in beta and is subject to change.
+
 </td></tr>
 <tr><td>permissions.organization_hooks</td><td>no</td><td>
 

docs/apps/scopeToken.md

@@ -82,11 +82,6 @@ The level of permission to grant the access token for checks on code.
 
 The level of permission to grant the access token for repository contents, commits, branches, downloads, releases, and merges.
 
-</td></tr>
-<tr><td>permissions.organization_custom_roles</td><td>no</td><td>
-
-The level of permission to grant the access token for custom roles management.
-
 </td></tr>
 <tr><td>permissions.deployments</td><td>no</td><td>
 
@@ -177,6 +172,11 @@ The level of permission to grant the access token for organization teams and mem
 
 The level of permission to grant the access token to manage access to an organization.
 
+</td></tr>
+<tr><td>permissions.organization_custom_roles</td><td>no</td><td>
+
+The level of permission to grant the access token for custom roles management. This property is in beta and is subject to change.
+
 </td></tr>
 <tr><td>permissions.organization_hooks</td><td>no</td><td>
 

docs/codeScanning/deleteAnalysis.md

@@ -31,8 +31,7 @@ where a set is determined by a unique combination of analysis values:
 
 - `ref`
 - `tool`
-- `analysis_key`
-- `environment`
+- `category`
 
 If you attempt to delete an analysis that is not the most recent in a set,
 you'll get a 400 response with the message:

docs/codeScanning/listRecentAnalyses.md

@@ -83,6 +83,16 @@ The Git reference for the analyses you want to list. The `ref` for a branch can
 
 Filter analyses belonging to the same SARIF upload.
 
+</td></tr>
+<tr><td>direction</td><td>no</td><td>
+
+The direction to sort the results by.
+
+</td></tr>
+<tr><td>sort</td><td>no</td><td>
+
+The property by which to sort the results.
+
 </td></tr>
   </tbody>
 </table>

docs/issues/update.md

@@ -63,6 +63,11 @@ Login for the user that this issue should be assigned to. **This field is deprec
 
 State of the issue. Either `open` or `closed`.
 
+</td></tr>
+<tr><td>state_reason</td><td>no</td><td>
+
+The reason for the current state
+
 </td></tr>
 <tr><td>milestone</td><td>no</td><td>
 

docs/orgs/listCustomRoles.md

@@ -11,6 +11,9 @@ type: API method
 List the custom repository roles available in this organization. In order to see custom
 repository roles in an organization, the authenticated user must be an organization owner.
 
+To use this endpoint the authenticated user must be an administrator for the organization or of an repository of the organizaiton and must use an access token with `admin:org repo` scope.
+GitHub Apps must have the `organization_custom_roles:read` organization permission to use this endpoint.
+
 For more information on custom repository roles, see "[Managing custom repository roles for an organization](https://docs.github.com/organizations/managing-peoples-access-to-your-organization-with-roles/managing-custom-repository-roles-for-an-organization)".
 
 ```js

docs/repos/createFork.md

@@ -49,6 +49,11 @@ Optional parameter to specify the organization name if forking into an organizat
 
 When forking from an existing repository, a new name for the fork.
 
+</td></tr>
+<tr><td>default_branch_only</td><td>no</td><td>
+
+When forking from an existing repository, fork with only the default branch.
+
 </td></tr>
   </tbody>
 </table>

docs/repos/getContent.md

@@ -16,11 +16,12 @@ retrieving the raw content or rendered HTML (when supported). All content types
 type](https://docs.github.com/rest/reference/repos#custom-media-types) to ensure the content is returned in a consistent
 object format.
 
-**Note**:
+**Notes**:
 
 - To get a repository's contents recursively, you can [recursively get the tree](https://docs.github.com/rest/reference/git#trees).
 - This API has an upper limit of 1,000 files for a directory. If you need to retrieve more files, use the [Git Trees
   API](https://docs.github.com/rest/reference/git#get-a-tree).
+- Download URLs expire and are meant to be used just once. To ensure the download URL does not expire, please use the contents API to obtain a fresh download URL for each download.
 
 #### Size limits
 

src/generated/method-types.ts

@@ -2855,8 +2855,7 @@ export type RestEndpointMethods = {
      *
      * * `ref`
      * * `tool`
-     * * `analysis_key`
-     * * `environment`
+     * * `category`
      *
      * If you attempt to delete an analysis that is not the most recent in a set,
      * you'll get a 400 response with the message:
@@ -6071,6 +6070,9 @@ export type RestEndpointMethods = {
      * List the custom repository roles available in this organization. In order to see custom
      * repository roles in an organization, the authenticated user must be an organization owner.
      *
+     * To use this endpoint the authenticated user must be an administrator for the organization or of an repository of the organizaiton and must use an access token with `admin:org repo` scope.
+     * GitHub Apps must have the `organization_custom_roles:read` organization permission to use this endpoint.
+     *
      * For more information on custom repository roles, see "[Managing custom repository roles for an organization](https://docs.github.com/organizations/managing-peoples-access-to-your-organization-with-roles/managing-custom-repository-roles-for-an-organization)".
      */
     listCustomRoles: {
@@ -8958,11 +8960,11 @@ export type RestEndpointMethods = {
      * type](https://docs.github.com/rest/reference/repos#custom-media-types) to ensure the content is returned in a consistent
      * object format.
      *
-     * **Note**:
+     * **Notes**:
      * *   To get a repository's contents recursively, you can [recursively get the tree](https://docs.github.com/rest/reference/git#trees).
      * *   This API has an upper limit of 1,000 files for a directory. If you need to retrieve more files, use the [Git Trees
      * API](https://docs.github.com/rest/reference/git#get-a-tree).
-     *
+     *  *  Download URLs expire and are meant to be used just once. To ensure the download URL does not expire, please use the contents API to obtain a fresh download URL for each download.
      * #### Size limits
      * If the requested file's size is:
      * * 1 MB or smaller: All features of this endpoint are supported.