chore: update usage and reference to include build approval (#393)

content/reference/cli/build/approve.md

@@ -0,0 +1,71 @@
+---
+title: "Approve"
+linkTitle: "Approve"
+description: >
+  Learn how to approve a build as a repository admin.
+---
+
+## Command
+
+```
+$ vela approve build <parameters...> <arguments...>
+```
+
+{{% alert color="info" %}}
+For more information, you can run `vela approve build --help`.
+{{% /alert %}}
+
+## Parameters
+
+The following parameters are used to configure the command:
+
+| Name     | Description                        | Environment Variables             |
+| -------- | ---------------------------------- | --------------------------------- |
+| `org`    | name of organization for the build | `VELA_ORG`, `BUILD_ORG`           |
+| `repo`   | name of repository for the build   | `VELA_REPO`, `BUILD_REPO`         |
+| `build`  | number of the build                | `VELA_BUILD`, `BUILD_NUMBER`      |
+| `output` | format the output for the build    | `VELA_OUTPUT`, `BUILD_OUTPUT`     |
+
+{{% alert color="info" %}}
+This command also supports setting the following parameters via a configuration file:
+
+- `org`
+- `repo`
+- `output`
+
+For more information, please review the [CLI config documentation](/docs/reference/cli/config/).
+{{% /alert %}}
+
+## Permissions
+
+COMING SOON!
+
+## Sample
+
+{{% alert color="warning" %}}
+This section assumes you have already installed and setup the CLI.
+
+To install the CLI, please review the [installation documentation](/docs/reference/cli/install/).
+
+To setup the CLI, please review the [authentication documentation](/docs/reference/cli/authentication/).
+{{% /alert %}}
+
+#### Request
+
+```sh
+$ pwd
+~/github/octocat
+$ vela approve build --build 1
+```
+
+#### Targeted Request
+
+```sh
+$ vela approve build --org github --repo octocat --build 1
+```
+
+#### Response
+
+```sh
+"successfully approved build github/octocat/1"
+```

content/reference/environment/variables.md

@@ -13,6 +13,8 @@ The following environment variables are injected into every step, service, or se
 
 | Key                       | Value                                                       | Explanation                                                         |
 | ------------------------- | ----------------------------------------------------------- | ------------------------------------------------------------------- |
+| `VELA_BUILD_APPROVED_AT`  | `1556720958`                                                | unix timestamp representing when build was approved                 |
+| `VELA_BUILD_APPROVED_BY`  | `RepoAdmin`                                                 | user who approved the build                                         |
 | `VELA_BUILD_AUTHOR`       | `octocat`                                                   | author from the source commit                                       |
 | `VELA_BUILD_AUTHOR_EMAIL` | `octocat@github.com`                                        | author email from the source commit, available only in `push` events                                 |
 | `VELA_BUILD_BASE_REF`     | `refs/heads/dev`                                            | reference from the base commit                                      |
@@ -24,6 +26,7 @@ The following environment variables are injected into every step, service, or se
 | `VELA_BUILD_DISTRIBUTION` | `linux`                                                     | distribution where the build was executed                           |
 | `VELA_BUILD_ENQUEUED`     | `1556720958`                                                | unix timestamp representing build enqueued time                     |
 | `VELA_BUILD_EVENT`        | `push`                                                      | webhook event that triggered the build                              |
+| `VELA_BUILD_EVENT_ACTION` | `created`                                                    | webhook event action that triggered the build                       |
 | `VELA_BUILD_HOST`         | `vela-worker-1`                                             | fully qualified domain name of the worker the build was executed on |
 | `VELA_BUILD_LINK`         | `https://vela.example.com/octocat/hello-world/1`       | link to the build in the UI                                         |
 | `VELA_BUILD_MESSAGE`      | `Merge pull request #6 from octocat/patch-1`                | message from the source commit                                      |
@@ -46,8 +49,10 @@ The following table includes variables only available during the **comment** eve
 
 | Key                       | Value | Explanation                                                |
 | ------------------------- | ----- | ---------------------------------------------------------- |
-| `VELA_BUILD_PULL_REQUEST` | `1`   | pull request number is populated from the source reference |
-| `VELA_PULL_REQUEST`       | `1`   | pull request number is populated from the source reference |
+| `VELA_BUILD_PULL_REQUEST`  | `1`    | pull request number is populated from the source reference |
+| `VELA_PULL_REQUEST`        | `1`    | pull request number is populated from the source reference |
+| `VELA_PULL_REQUEST_SOURCE` | `dev`  | pull request branch from the source reference              |
+| `VELA_PULL_REQUEST_TARGET` | `main` | pull request branch for the target reference               |
 
 ##### `deployment` event only
 
@@ -57,10 +62,11 @@ The following table includes variables only available during the **deployment**
 All custom parameters are passed to the deployment available with a `DEPLOYMENT_PARAMETER_` prefix of the key.
 {{% /alert %}}
 
-| Key                 | Value        | Explanation                                   |
-| ------------------- | -----------  | --------------------------------------------- |
-| `VELA_BUILD_TARGET` | `production` | name of target environment for the deployment |
-| `VELA_DEPLOYMENT`   | `production` | name of target environment for the deployment |
+| Key                      | Value        | Explanation                                   |
+| ------------------------ | -----------  | --------------------------------------------- |
+| `VELA_BUILD_TARGET`      | `production` | name of target environment for the deployment |
+| `VELA_DEPLOYMENT`        | `production` | name of target environment for the deployment |
+| `VELA_DEPLOYMENT_NUMBER` | `12345`      | ID of deployment from source                  |
 
 ##### `pull_request` event only
 

content/usage/repo_settings.md

@@ -37,6 +37,20 @@ Vela supports two options for visibility: **private** or **any**. This determine
 
 By default, a newly enabled repository will inherit the visibility setting it has with the source control manager. However, if a user wishes for the visbility to differ between the source code repository and the CI repository, they can do so by changing this setting.
 
+### Outside Contributor Permissions
+
+This setting allows repository admins to further safeguard their repositories by requiring approval for builds, specifically pull requests from forks.
+
+The three settings are:
+
+- **Always Require Approval**: regardless of user, if the webhook event is a pull request from a fork, the build will need to be approved by a repository admin.
+- **Require Approval For Read-Only**: some teams prefer the fork contribution workflow even if users have write permission to the repo. This setting allows those users to not need approval, but read-only users will.
+- **Never Require Approval**: any user will be able to run pull request builds by opening a PR against the repository.
+
+When a build is awaiting approval, the SCM will be updated with the status `pending` with the description `build needs approval from repo admin to run`. 
+
+Repository admins can approve a build in the UI or by using the [CLI](/docs/reference/cli/build/approve).
+
 ### Build Limit
 
 The default and max build limit is determined by the platform administrators. These values determine how many builds can be run concurrently for any given repository. These limits exist to prevent any single repository from occupying a large amount of worker resources.