feat: octokit.codeScanning.listRecentAnalyses, `octokit.codeScannin…

…g.updateAlert`, `octokit.codeScanning.uploadSarif`. Deprecation: `alert_id` parameter has been deprecated. Use `alert_number` instead (#217)

docs/actions/createOrUpdateOrgSecret.md

@@ -52,7 +52,7 @@ def encrypt(public_key: str, secret_value: str) -> str:
   return b64encode(encrypted).decode("utf-8")
 ```
 
-#### Example encrypting a secret using C
+#### Example encrypting a secret using C#
 
 Encrypt your secret using the [Sodium.Core](https://www.nuget.org/packages/Sodium.Core/) package.
 

docs/actions/createOrUpdateRepoSecret.md

@@ -52,7 +52,7 @@ def encrypt(public_key: str, secret_value: str) -> str:
   return b64encode(encrypted).decode("utf-8")
 ```
 
-#### Example encrypting a secret using C
+#### Example encrypting a secret using C#
 
 Encrypt your secret using the [Sodium.Core](https://www.nuget.org/packages/Sodium.Core/) package.
 

docs/codeScanning/getAlert.md

@@ -1,22 +1,20 @@
 ---
 name: Get a code scanning alert
-example: octokit.codeScanning.getAlert({ owner, repo, alert_id })
-route: GET /repos/{owner}/{repo}/code-scanning/alerts/{alert_id}
+example: octokit.codeScanning.getAlert({ owner, repo })
+route: GET /repos/{owner}/{repo}/code-scanning/alerts/{alert_number}
 scope: codeScanning
 type: API method
 ---
 
 # Get a code scanning alert
 
-Gets a single code scanning alert. You must use an access token with the `security_events` scope to use this endpoint. GitHub Apps must have the `security_events` read permission to use this endpoint.
-
-The security `alert_id` is found at the end of the security alert's URL. For example, the security alert ID for `https://github.com/Octo-org/octo-repo/security/code-scanning/88` is `88`.
+Gets a single code scanning alert. For private repos, you must use an access token with the `repo` scope. For public repos, you must use an access token with `public_repo` and `repo:security_events` scopes.
+GitHub Apps must have the `security_events` read permission to use this endpoint.
 
 ```js
 octokit.codeScanning.getAlert({
   owner,
   repo,
-  alert_id,
 });
 ```
 
@@ -37,7 +35,12 @@ octokit.codeScanning.getAlert({
 <tr><td>repo</td><td>yes</td><td>
 
 </td></tr>
-<tr><td>alert_id</td><td>yes</td><td>
+<tr><td>alert_number</td><td>no</td><td>
+
+The code scanning alert number.
+
+</td></tr>
+<tr><td>alert_id</td><td>no</td><td>
 
 </td></tr>
   </tbody>

docs/codeScanning/listAlertsForRepo.md

@@ -8,7 +8,7 @@ type: API method
 
 # List code scanning alerts for a repository
 
-Lists all open code scanning alerts for the default branch (usually `master`) and protected branches in a repository. You must use an access token with the `security_events` scope to use this endpoint. GitHub Apps must have the `security_events` read permission to use this endpoint.
+Lists all open code scanning alerts for the default branch (usually `master`) and protected branches in a repository. For private repos, you must use an access token with the `repo` scope. For public repos, you must use an access token with `public_repo` and `repo:security_events` scopes. GitHub Apps must have the `security_events` read permission to use this endpoint.
 
 ```js
 octokit.codeScanning.listAlertsForRepo({
@@ -36,12 +36,12 @@ octokit.codeScanning.listAlertsForRepo({
 </td></tr>
 <tr><td>state</td><td>no</td><td>
 
-Set to `closed` to list only closed code scanning alerts.
+Set to `open`, `fixed`, or `dismissed` to list code scanning alerts in a specific state.
 
 </td></tr>
 <tr><td>ref</td><td>no</td><td>
 
-Returns a list of code scanning alerts for a specific brach reference. The `ref` must be formatted as `heads/<branch name>`.
+Set a full Git reference to list alerts for a specific branch. The `ref` must be formatted as `refs/heads/<branch name>`.
 
 </td></tr>
   </tbody>

docs/codeScanning/listRecentAnalyses.md

@@ -0,0 +1,50 @@
+---
+name: List recent code scanning analyses for a repository
+example: octokit.codeScanning.listRecentAnalyses({ owner, repo })
+route: GET /repos/{owner}/{repo}/code-scanning/analyses
+scope: codeScanning
+type: API method
+---
+
+# List recent code scanning analyses for a repository
+
+List the details of recent code scanning analyses for a repository. For private repos, you must use an access token with the `repo` scope. For public repos, you must use an access token with `public_repo` and `repo:security_events` scopes. GitHub Apps must have the `security_events` read permission to use this endpoint.
+
+```js
+octokit.codeScanning.listRecentAnalyses({
+  owner,
+  repo,
+});
+```
+
+## Parameters
+
+<table>
+  <thead>
+    <tr>
+      <th>name</th>
+      <th>required</th>
+      <th>description</th>
+    </tr>
+  </thead>
+  <tbody>
+    <tr><td>owner</td><td>yes</td><td>
+
+</td></tr>
+<tr><td>repo</td><td>yes</td><td>
+
+</td></tr>
+<tr><td>ref</td><td>no</td><td>
+
+Set a full Git reference to list alerts for a specific branch. The `ref` must be formatted as `refs/heads/<branch name>`.
+
+</td></tr>
+<tr><td>tool_name</td><td>no</td><td>
+
+Set a single code scanning tool name to filter alerts by tool.
+
+</td></tr>
+  </tbody>
+</table>
+
+See also: [GitHub Developer Guide documentation](https://developer.github.com/v3/code-scanning/#list-recent-analyses).

docs/codeScanning/updateAlert.md

@@ -0,0 +1,57 @@
+---
+name: Update a code scanning alert
+example: octokit.codeScanning.updateAlert({ owner, repo, state })
+route: PATCH /repos/{owner}/{repo}/code-scanning/alerts/{alert_number}
+scope: codeScanning
+type: API method
+---
+
+# Update a code scanning alert
+
+Updates the status of a single code scanning alert. For private repos, you must use an access token with the `repo` scope. For public repos, you must use an access token with `public_repo` and `repo:security_events` scopes.
+GitHub Apps must have the `security_events` write permission to use this endpoint.
+
+```js
+octokit.codeScanning.updateAlert({
+  owner,
+  repo,
+  state,
+});
+```
+
+## Parameters
+
+<table>
+  <thead>
+    <tr>
+      <th>name</th>
+      <th>required</th>
+      <th>description</th>
+    </tr>
+  </thead>
+  <tbody>
+    <tr><td>owner</td><td>yes</td><td>
+
+</td></tr>
+<tr><td>repo</td><td>yes</td><td>
+
+</td></tr>
+<tr><td>alert_number</td><td>no</td><td>
+
+The code scanning alert number.
+
+</td></tr>
+<tr><td>state</td><td>yes</td><td>
+
+Sets the state of the code scanning alert. Can be one of `open` or `dismissed`. You must provide `dismissed_reason` when you set the state to `dismissed`.
+
+</td></tr>
+<tr><td>dismissed_reason</td><td>no</td><td>
+
+**Required when the state is dismissed.** The reason for dismissing or closing the alert. Can be one of: `false positive`, `won't fix`, and `used in tests`.
+
+</td></tr>
+  </tbody>
+</table>
+
+See also: [GitHub Developer Guide documentation](https://developer.github.com/v3/code-scanning/#upload-a-code-scanning-alert).

docs/codeScanning/uploadSarif.md

@@ -0,0 +1,76 @@
+---
+name: Upload a SARIF file
+example: octokit.codeScanning.uploadSarif({ owner, repo, commit_sha, ref, sarif, tool_name })
+route: POST /repos/{owner}/{repo}/code-scanning/sarifs
+scope: codeScanning
+type: API method
+---
+
+# Upload a SARIF file
+
+Upload a SARIF file containing the results of a code scanning analysis to make the results available in a repository.
+For private repos, you must use an access token with the `repo` scope. For public repos, you must use an access token with `public_repo` and `repo:security_events` scopes. GitHub Apps must have the `security_events` write permission to use this endpoint.
+
+```js
+octokit.codeScanning.uploadSarif({
+  owner,
+  repo,
+  commit_sha,
+  ref,
+  sarif,
+  tool_name,
+});
+```
+
+## Parameters
+
+<table>
+  <thead>
+    <tr>
+      <th>name</th>
+      <th>required</th>
+      <th>description</th>
+    </tr>
+  </thead>
+  <tbody>
+    <tr><td>owner</td><td>yes</td><td>
+
+</td></tr>
+<tr><td>repo</td><td>yes</td><td>
+
+</td></tr>
+<tr><td>commit_sha</td><td>yes</td><td>
+
+The commit SHA of the code scanning analysis file.
+
+</td></tr>
+<tr><td>ref</td><td>yes</td><td>
+
+The full Git reference of the code scanning analysis file, formatted as `refs/heads/<branch name>`.
+
+</td></tr>
+<tr><td>sarif</td><td>yes</td><td>
+
+A 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.
+
+</td></tr>
+<tr><td>checkout_uri</td><td>no</td><td>
+
+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.
+
+</td></tr>
+<tr><td>started_at</td><td>no</td><td>
+
+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`.
+
+</td></tr>
+<tr><td>tool_name</td><td>yes</td><td>
+
+The name of the tool used to generate the code scanning analysis alert.
+
+</td></tr>
+  </tbody>
+</table>
+
+See also: [GitHub Developer Guide documentation](https://developer.github.com/v3/code-scanning/#upload-a-sarif-analysis).

docs/git/createCommit.md

@@ -10,12 +10,17 @@ type: API method
 
 Creates a new Git [commit object](https://git-scm.com/book/en/v1/Git-Internals-Git-Objects#Commit-Objects).
 
-In this example, the payload of the signature would be:
-
 **Signature verification object**
 
 The response will include a `verification` object that describes the result of verifying the commit's signature. The following fields are included in the `verification` object:
 
+| Name        | Type      | Description                                                                                      |
+| ----------- | --------- | ------------------------------------------------------------------------------------------------ |
+| `verified`  | `boolean` | Indicates whether GitHub considers the signature in this commit to be verified.                  |
+| `reason`    | `string`  | The reason for verified value. Possible values and their meanings are enumerated in table below. |
+| `signature` | `string`  | The signature that was extracted from the commit.                                                |
+| `payload`   | `string`  | The value that was signed.                                                                       |
+
 These are the possible values for `reason` in the `verification` object:
 
 | Value                    | Description                                                                                                                       |

docs/git/createTag.md

@@ -14,6 +14,13 @@ Note that creating a tag object does not create the reference that makes a tag i
 
 The response will include a `verification` object that describes the result of verifying the commit's signature. The following fields are included in the `verification` object:
 
+| Name        | Type      | Description                                                                                      |
+| ----------- | --------- | ------------------------------------------------------------------------------------------------ |
+| `verified`  | `boolean` | Indicates whether GitHub considers the signature in this commit to be verified.                  |
+| `reason`    | `string`  | The reason for verified value. Possible values and their meanings are enumerated in table below. |
+| `signature` | `string`  | The signature that was extracted from the commit.                                                |
+| `payload`   | `string`  | The value that was signed.                                                                       |
+
 These are the possible values for `reason` in the `verification` object:
 
 | Value                    | Description                                                                                                                       |

docs/git/getCommit.md

@@ -14,6 +14,13 @@ Gets a Git [commit object](https://git-scm.com/book/en/v1/Git-Internals-Git-Obje
 
 The response will include a `verification` object that describes the result of verifying the commit's signature. The following fields are included in the `verification` object:
 
+| Name        | Type      | Description                                                                                      |
+| ----------- | --------- | ------------------------------------------------------------------------------------------------ |
+| `verified`  | `boolean` | Indicates whether GitHub considers the signature in this commit to be verified.                  |
+| `reason`    | `string`  | The reason for verified value. Possible values and their meanings are enumerated in table below. |
+| `signature` | `string`  | The signature that was extracted from the commit.                                                |
+| `payload`   | `string`  | The value that was signed.                                                                       |
+
 These are the possible values for `reason` in the `verification` object:
 
 | Value                    | Description                                                                                                                       |

docs/git/getTag.md

@@ -12,6 +12,13 @@ type: API method
 
 The response will include a `verification` object that describes the result of verifying the commit's signature. The following fields are included in the `verification` object:
 
+| Name        | Type      | Description                                                                                      |
+| ----------- | --------- | ------------------------------------------------------------------------------------------------ |
+| `verified`  | `boolean` | Indicates whether GitHub considers the signature in this commit to be verified.                  |
+| `reason`    | `string`  | The reason for verified value. Possible values and their meanings are enumerated in table below. |
+| `signature` | `string`  | The signature that was extracted from the commit.                                                |
+| `payload`   | `string`  | The value that was signed.                                                                       |
+
 These are the possible values for `reason` in the `verification` object:
 
 | Value                    | Description                                                                                                                       |

docs/orgs/setMembershipForUser.md

@@ -11,7 +11,6 @@ type: API method
 Only authenticated organization owners can add a member to the organization or update the member's role.
 
 - If the authenticated user is _adding_ a member to the organization, the invited user will receive an email inviting them to the organization. The user's [membership status](https://developer.github.com/v3/orgs/members/#get-organization-membership-for-a-user) will be `pending` until they accept the invitation.
-
 - Authenticated users can _update_ a user's membership by passing the `role` parameter. If the authenticated user changes a member's role to `admin`, the affected user will receive an email notifying them that they've been made an organization owner. If the authenticated user changes an owner's role to `member`, no email will be sent.
 
 **Rate limits**

docs/repos/compareCommits.md

@@ -18,12 +18,20 @@ The response also includes details on the files that were changed between the tw
 
 The response will include a comparison of up to 250 commits. If you are working with a larger commit range, you can use the [List commits](https://developer.github.com/v3/repos/commits/#list-commits) to enumerate all commits in the range.
 
-For comparisons with extremely large diffs, you may receive an error response indicating that the diff took too long to generate. You can typically resolve this error by using a smaller commit range.
+For comparisons with extremely large diffs, you may receive an error response indicating that the diff took too long
+to generate. You can typically resolve this error by using a smaller commit range.
 
 **Signature verification object**
 
 The response will include a `verification` object that describes the result of verifying the commit's signature. The following fields are included in the `verification` object:
 
+| Name        | Type      | Description                                                                                      |
+| ----------- | --------- | ------------------------------------------------------------------------------------------------ |
+| `verified`  | `boolean` | Indicates whether GitHub considers the signature in this commit to be verified.                  |
+| `reason`    | `string`  | The reason for verified value. Possible values and their meanings are enumerated in table below. |
+| `signature` | `string`  | The signature that was extracted from the commit.                                                |
+| `payload`   | `string`  | The value that was signed.                                                                       |
+
 These are the possible values for `reason` in the `verification` object:
 
 | Value                    | Description                                                                                                                       |