docs: updated to latest OpenAPI spec

Author: gr2m

docs/actions/createOrUpdateOrgSecret.md

@@ -8,16 +8,81 @@ type: API method
 
 # Create or update an organization secret
 
-Creates or updates an organization secret with an encrypted value. Encrypt your secret using [LibSodium](https://libsodium.gitbook.io/doc/bindings_for_other_languages). You must authenticate using an access token with the `admin:org` scope to use this endpoint. GitHub Apps must have the `secrets` organization permission to use this endpoint.
+Creates or updates an organization secret with an encrypted value. Encrypt your secret using
+[LibSodium](https://libsodium.gitbook.io/doc/bindings_for_other_languages). You must authenticate using an access
+token with the `admin:org` scope to use this endpoint. GitHub Apps must have the `secrets` organization permission to
+use this endpoint.
+
+#### Example encrypting a secret using Node.js
 
 Encrypt your secret using the [tweetsodium](https://github.com/github/tweetsodium) library.
 
+```
+const sodium = require('tweetsodium');
+
+const key = "base64-encoded-public-key";
+const value = "plain-text-secret";
+
+// Convert the message and key to Uint8Array's (Buffer implements that interface)
+const messageBytes = Buffer.from(value);
+const keyBytes = Buffer.from(key, 'base64');
+
+// Encrypt using LibSodium.
+const encryptedBytes = sodium.seal(messageBytes, keyBytes);
+
+// Base64 the encrypted secret
+const encrypted = Buffer.from(encryptedBytes).toString('base64');
+
+console.log(encrypted);
+```
+
+#### Example encrypting a secret using Python
+
 Encrypt your secret using [pynacl](https://pynacl.readthedocs.io/en/stable/public/#nacl-public-sealedbox) with Python 3.
 
+```
+from base64 import b64encode
+from nacl import encoding, public
+
+def encrypt(public_key: str, secret_value: str) -> str:
+  """Encrypt a Unicode string using the public key."""
+  public_key = public.PublicKey(public_key.encode("utf-8"), encoding.Base64Encoder())
+  sealed_box = public.SealedBox(public_key)
+  encrypted = sealed_box.encrypt(secret_value.encode("utf-8"))
+  return b64encode(encrypted).decode("utf-8")
+```
+
+#### Example encrypting a secret using C
+
 Encrypt your secret using the [Sodium.Core](https://www.nuget.org/packages/Sodium.Core/) package.
 
+```
+var secretValue = System.Text.Encoding.UTF8.GetBytes("mySecret");
+var publicKey = Convert.FromBase64String("2Sg8iYjAxxmI2LvUXpJjkYrMxURPc8r+dB7TJyvvcCU=");
+
+var sealedPublicKeyBox = Sodium.SealedPublicKeyBox.Create(secretValue, publicKey);
+
+Console.WriteLine(Convert.ToBase64String(sealedPublicKeyBox));
+```
+
+#### Example encrypting a secret using Ruby
+
 Encrypt your secret using the [rbnacl](https://github.com/RubyCrypto/rbnacl) gem.
 
+```ruby
+require "rbnacl"
+require "base64"
+
+key = Base64.decode64("+ZYvJDZMHUfBkJdyq5Zm9SKqeuBQ4sj+6sfjlH4CgG0=")
+public_key = RbNaCl::PublicKey.new(key)
+
+box = RbNaCl::Boxes::Sealed.from_public_key(public_key)
+encrypted_secret = box.encrypt("my_secret")
+
+# Print the base64 encoded secret
+puts Base64.strict_encode64(encrypted_secret)
+```
+
 ```js
 octokit.actions.createOrUpdateOrgSecret({
   org,
@@ -54,9 +119,9 @@ ID of the key you used to encrypt the secret.
 </td></tr>
 <tr><td>visibility</td><td>no</td><td>
 
-Configures the access that repositories have to the organization secret. Can be one of:  
-\- `all` - All repositories in an organization can access the secret.  
-\- `private` - Private repositories in an organization can access the secret.  
+Configures the access that repositories have to the organization secret. Can be one of:
+\- `all` - All repositories in an organization can access the secret.
+\- `private` - Private repositories in an organization can access the secret.
 \- `selected` - Only specific repositories can access the secret.
 
 </td></tr>

docs/actions/createOrUpdateRepoSecret.md

@@ -8,16 +8,81 @@ type: API method
 
 # Create or update a repository secret
 
-Creates or updates a repository secret with an encrypted value. Encrypt your secret using [LibSodium](https://libsodium.gitbook.io/doc/bindings_for_other_languages). You must authenticate using an access token with the `repo` scope to use this endpoint. GitHub Apps must have the `secrets` repository permission to use this endpoint.
+Creates or updates a repository secret with an encrypted value. Encrypt your secret using
+[LibSodium](https://libsodium.gitbook.io/doc/bindings_for_other_languages). You must authenticate using an access
+token with the `repo` scope to use this endpoint. GitHub Apps must have the `secrets` repository permission to use
+this endpoint.
+
+#### Example encrypting a secret using Node.js
 
 Encrypt your secret using the [tweetsodium](https://github.com/github/tweetsodium) library.
 
+```
+const sodium = require('tweetsodium');
+
+const key = "base64-encoded-public-key";
+const value = "plain-text-secret";
+
+// Convert the message and key to Uint8Array's (Buffer implements that interface)
+const messageBytes = Buffer.from(value);
+const keyBytes = Buffer.from(key, 'base64');
+
+// Encrypt using LibSodium.
+const encryptedBytes = sodium.seal(messageBytes, keyBytes);
+
+// Base64 the encrypted secret
+const encrypted = Buffer.from(encryptedBytes).toString('base64');
+
+console.log(encrypted);
+```
+
+#### Example encrypting a secret using Python
+
 Encrypt your secret using [pynacl](https://pynacl.readthedocs.io/en/stable/public/#nacl-public-sealedbox) with Python 3.
 
+```
+from base64 import b64encode
+from nacl import encoding, public
+
+def encrypt(public_key: str, secret_value: str) -> str:
+  """Encrypt a Unicode string using the public key."""
+  public_key = public.PublicKey(public_key.encode("utf-8"), encoding.Base64Encoder())
+  sealed_box = public.SealedBox(public_key)
+  encrypted = sealed_box.encrypt(secret_value.encode("utf-8"))
+  return b64encode(encrypted).decode("utf-8")
+```
+
+#### Example encrypting a secret using C
+
 Encrypt your secret using the [Sodium.Core](https://www.nuget.org/packages/Sodium.Core/) package.
 
+```
+var secretValue = System.Text.Encoding.UTF8.GetBytes("mySecret");
+var publicKey = Convert.FromBase64String("2Sg8iYjAxxmI2LvUXpJjkYrMxURPc8r+dB7TJyvvcCU=");
+
+var sealedPublicKeyBox = Sodium.SealedPublicKeyBox.Create(secretValue, publicKey);
+
+Console.WriteLine(Convert.ToBase64String(sealedPublicKeyBox));
+```
+
+#### Example encrypting a secret using Ruby
+
 Encrypt your secret using the [rbnacl](https://github.com/RubyCrypto/rbnacl) gem.
 
+```ruby
+require "rbnacl"
+require "base64"
+
+key = Base64.decode64("+ZYvJDZMHUfBkJdyq5Zm9SKqeuBQ4sj+6sfjlH4CgG0=")
+public_key = RbNaCl::PublicKey.new(key)
+
+box = RbNaCl::Boxes::Sealed.from_public_key(public_key)
+encrypted_secret = box.encrypt("my_secret")
+
+# Print the base64 encoded secret
+puts Base64.strict_encode64(encrypted_secret)
+```
+
 ```js
 octokit.actions.createOrUpdateRepoSecret({
   owner,

docs/actions/createRegistrationTokenForOrg.md

@@ -10,10 +10,17 @@ type: API method
 
 **Warning:** The self-hosted runners API for organizations is currently in public beta and subject to change.
 
-Returns a token that you can pass to the `config` script. The token expires after one hour. You must authenticate using an access token with the `admin:org` scope to use this endpoint.
+Returns a token that you can pass to the `config` script. The token expires after one hour. You must authenticate
+using an access token with the `admin:org` scope to use this endpoint.
+
+#### Example using registration token
 
 Configure your self-hosted runner, replacing `TOKEN` with the registration token provided by this endpoint.
 
+```
+./config.sh --url https://github.com/octo-org --token TOKEN
+```
+
 ```js
 octokit.actions.createRegistrationTokenForOrg({
   org,

docs/actions/createRegistrationTokenForRepo.md

@@ -8,9 +8,16 @@ type: API method
 
 # Create a registration token for a repository
 
-Returns a token that you can pass to the `config` script. The token expires after one hour. You must authenticate using an access token with the `repo` scope to use this endpoint.
+Returns a token that you can pass to the `config` script. The token expires after one hour. You must authenticate
+using an access token with the `repo` scope to use this endpoint.
 
-Configure your self-hosted runner, replacing TOKEN with the registration token provided by this endpoint.
+#### Example using registration token
+
+Configure your self-hosted runner, replacing `TOKEN` with the registration token provided by this endpoint.
+
+```
+./config.sh --url https://github.com/octo-org/octo-repo-artifacts --token TOKEN
+```
 
 ```js
 octokit.actions.createRegistrationTokenForRepo({

docs/actions/createRemoveTokenForOrg.md

@@ -10,9 +10,18 @@ type: API method
 
 **Warning:** The self-hosted runners API for organizations is currently in public beta and subject to change.
 
-Returns a token that you can pass to the `config` script to remove a self-hosted runner from an organization. The token expires after one hour. You must authenticate using an access token with the `admin:org` scope to use this endpoint.
+Returns a token that you can pass to the `config` script to remove a self-hosted runner from an organization. The
+token expires after one hour. You must authenticate using an access token with the `admin:org` scope to use this
+endpoint.
 
-To remove your self-hosted runner from an organization, replace `TOKEN` with the remove token provided by this endpoint.
+#### Example using remove token
+
+To remove your self-hosted runner from an organization, replace `TOKEN` with the remove token provided by this
+endpoint.
+
+```
+./config.sh remove --token TOKEN
+```
 
 ```js
 octokit.actions.createRemoveTokenForOrg({

docs/actions/createRemoveTokenForRepo.md

@@ -8,9 +8,16 @@ type: API method
 
 # Create a remove token for a repository
 
-Returns a token that you can pass to remove a self-hosted runner from a repository. The token expires after one hour. You must authenticate using an access token with the `repo` scope to use this endpoint.
+Returns a token that you can pass to remove a self-hosted runner from a repository. The token expires after one hour.
+You must authenticate using an access token with the `repo` scope to use this endpoint.
 
-Remove your self-hosted runner from a repository, replacing TOKEN with the remove token provided by this endpoint.
+#### Example using remove token
+
+To remove your self-hosted runner from a repository, replace TOKEN with the remove token provided by this endpoint.
+
+```
+./config.sh remove --token TOKEN
+```
 
 ```js
 octokit.actions.createRemoveTokenForRepo({

docs/actions/createWorkflowDispatch.md

@@ -0,0 +1,62 @@
+---
+name: Create a workflow dispatch event
+example: octokit.actions.createWorkflowDispatch({ owner, repo, workflow_id, ref })
+route: POST /repos/{owner}/{repo}/actions/workflows/{workflow_id}/dispatches
+scope: actions
+type: API method
+---
+
+# Create a workflow dispatch event
+
+You can use this endpoint to manually trigger a GitHub Actions workflow run. You can also replace `{workflow_id}` with the workflow file name. For example, you could use `main.yml`.
+
+You must configure your GitHub Actions workflow to run when the [`workflow_dispatch` webhook](/developers/webhooks-and-events/webhook-events-and-payloads#workflow_dispatch) event occurs. The `inputs` are configured in the workflow file. For more information about how to configure the `workflow_dispatch` event in the workflow file, see "[Events that trigger workflows](/actions/reference/events-that-trigger-workflows#workflow_dispatch)."
+
+You must authenticate using an access token with the `repo` scope to use this endpoint. GitHub Apps must have the `actions:write` permission to use this endpoint. For more information, see "[Creating a personal access token for the command line](https://help.github.com/articles/creating-a-personal-access-token-for-the-command-line)."
+
+```js
+octokit.actions.createWorkflowDispatch({
+  owner,
+  repo,
+  workflow_id,
+  ref,
+});
+```
+
+## 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>workflow_id</td><td>yes</td><td>
+
+</td></tr>
+<tr><td>ref</td><td>yes</td><td>
+
+The reference of the workflow run. The reference can be a branch, tag, or a commit SHA.
+
+</td></tr>
+<tr><td>inputs</td><td>no</td><td>
+
+Input keys and values configured in the workflow file. The maximum number of properties is 10.
+
+</td></tr>
+<tr><td>inputs.*</td><td>no</td><td>
+
+</td></tr>
+  </tbody>
+</table>
+
+See also: [GitHub Developer Guide documentation](https://developer.github.com/v3/actions/workflows/#create-a-workflow-dispatch-event).

docs/actions/deleteWorkflowRun.md

@@ -0,0 +1,46 @@
+---
+name: Delete a workflow run
+example: octokit.actions.deleteWorkflowRun({ owner, repo, run_id })
+route: DELETE /repos/{owner}/{repo}/actions/runs/{run_id}
+scope: actions
+type: API method
+---
+
+# Delete a workflow run
+
+Delete a specific workflow run. Anyone with write access to the repository can use this endpoint. If the repository is
+private you must use an access token with the `repo` scope. GitHub Apps must have the `actions:write` permission to use
+this endpoint.
+
+```js
+octokit.actions.deleteWorkflowRun({
+  owner,
+  repo,
+  run_id,
+});
+```
+
+## 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>run_id</td><td>yes</td><td>
+
+</td></tr>
+  </tbody>
+</table>
+
+See also: [GitHub Developer Guide documentation](https://developer.github.com/v3/actions/workflow-runs/#delete-a-workflow-run).

docs/actions/downloadArtifact.md

@@ -8,9 +8,10 @@ type: API method
 
 # Download an artifact
 
-Gets a redirect URL to download an archive for a repository. This URL expires after 1 minute. Look for `Location:` in the response header to find the URL for the download. The `:archive_format` must be `zip`. Anyone with read access to the repository can use this endpoint. If the repository is private you must use an access token with the `repo` scope. GitHub Apps must have the `actions:read` permission to use this endpoint.
-
-Call this endpoint using the `-v` flag, which enables verbose output and allows you to see the download URL in the header. To download the file into the current working directory, specify the filename using the `-o` flag.
+Gets a redirect URL to download an archive for a repository. This URL expires after 1 minute. Look for `Location:` in
+the response header to find the URL for the download. The `:archive_format` must be `zip`. Anyone with read access to
+the repository can use this endpoint. If the repository is private you must use an access token with the `repo` scope.
+GitHub Apps must have the `actions:read` permission to use this endpoint.
 
 ```js
 octokit.actions.downloadArtifact({

docs/actions/downloadJobLogsForWorkflowRun.md

@@ -8,9 +8,10 @@ type: API method
 
 # Download job logs for a workflow run
 
-Gets a redirect URL to download a plain text file of logs for a workflow job. This link expires after 1 minute. Look for `Location:` in the response header to find the URL for the download. Anyone with read access to the repository can use this endpoint. If the repository is private you must use an access token with the `repo` scope. GitHub Apps must have the `actions:read` permission to use this endpoint.
-
-Call this endpoint using the `-v` flag, which enables verbose output and allows you to see the download URL in the header. To download the file into the current working directory, specify the filename using the `-o` flag.
+Gets a redirect URL to download a plain text file of logs for a workflow job. This link expires after 1 minute. Look
+for `Location:` in the response header to find the URL for the download. Anyone with read access to the repository can
+use this endpoint. If the repository is private you must use an access token with the `repo` scope. GitHub Apps must
+have the `actions:read` permission to use this endpoint.
 
 ```js
 octokit.actions.downloadJobLogsForWorkflowRun({