Merge pull request #375 from github/deployment-confirmation-docs

Deployment confirmation docs

Author: GrantBirki

Diff for: README.md

@@ -301,7 +301,7 @@ As seen above, we have two steps. One for a noop deploy, and one for a regular d
 | `enforced_deployment_order` | `false` | `""` | A comma separated list of environments that must be deployed in a specific order. Example: `"development,staging,production"`. If this is set then you cannot deploy to latter environments unless the former ones have a successful and active deployment on the latest commit first - See the [enforced deployment order docs](./docs/enforced-deployment-order.md) for more details |
 | `use_security_warnings` | `false` | `"true"` | Whether or not to leave security related warnings in log messages during deployments. Default is `"true"` |
 | `allow_non_default_target_branch_deployments` | `false` | `"false"` | Whether or not to allow deployments of pull requests that target a branch other than the default branch (aka stable branch) as their merge target. By default, this Action would reject the deployment of a branch named `feature-branch` if it was targeting `foo` instead of `main` (or whatever your default branch is). This option allows you to override that behavior and be able to deploy any branch in your repository regardless of the target branch. This option is potentially unsafe and should be used with caution as most default branches contain branch protection rules. Often times non-default branches do not contain these same branch protection rules. Follow along in this [issue thread](https://github.com/github/branch-deploy/issues/340) to learn more. |
-| `deployment_confirmation` | `false` | `"false"` | Whether or not to require an additional confirmation before a deployment can continue. Default is `"false"`. If your project requires elevated security, it is highly recommended to enable this option - especially in open source projects where you might be deploying forks. |
+| `deployment_confirmation` | `false` | `"false"` | Whether or not to require an additional confirmation before a deployment can continue. Default is `"false"`. If your project requires elevated security, it is highly recommended to enable this option - especially in open source projects where you might be deploying forks - [Deployment confirmation docs](./docs/deployment-confirmation.md) |
 | `deployment_confirmation_timeout` | `false` | `60` | The number of seconds to wait for a deployment confirmation before timing out. Default is `60` seconds (1 minute). |
 
 ## Outputs 📤

Diff for: action.yml

@@ -194,7 +194,7 @@ inputs:
     required: false
     default: "false"
   deployment_confirmation:
-    description: 'Whether or not to require an additional confirmation before a deployment can continue. Default is "false". If your project requires elevated security, it is highly recommended to enable this option - especially in open source projects where you might be deploying forks.'
+    description: 'Whether or not to require an additional confirmation before a deployment can continue. Default is "false". If your project requires elevated security, it is highly recommended to enable this option - especially in open source projects where you might be deploying forks. docs/deployment-confirmation.md'
     required: false
     default: "false"
   deployment_confirmation_timeout:

Diff for: docs/assets/deployment-approved.png

@@ -0,0 +1,51 @@
+# Deployment Confirmation
+
+## Overview
+
+For projects that require the highest level of deployment safety/security, the branch-deploy Action can be configured to require a deployment **confirmation** before a deployment is allowed to proceed.
+
+This can be considered a "final safety check" before a deployment can continue.
+
+By using this feature, it is also an extremely effective way to prevent accidental or malicious commits from being deployed without first having one last safety review. This is important for hardening against Actions related [TOCTOU](https://github.com/AdnaneKhan/ActionsTOCTOU) vulnerabilities.
+## How it works
+
+When a user invokes a deployment via the `.deploy` (or `.noop`) command, the branch-deploy Action will pause _just_ before the final call to start a deployment by this Action. The Action will then create a new comment on the pull request that invoked the deployment, asking the user to confirm (or reject) the deployment.
+
+This comment will provide the user with a summary of the deployment that is **about** to be run. The user will then have the opportunity to confirm (with a 👍) or deny (with a 👎) the deployment.
+
+Depending on the user's response (or lack of response), the branch-deploy Action will update the comment with the outcome.
+
+The only reaction (👍 or 👎) that will be considered is the first reaction from the original actor that invoked the deployment (via `.deploy`). For example, if `@monalisa` comments `.deploy`, only `@monalisa` can give deployment confirmation via a reaction. All other reactions will be ignored on the deployment confirmation comment.
+
+### Usage
+
+```yaml
+      - uses: github/[email protected]
+        id: branch-deploy
+        with:
+          trigger: ".deploy"
+          deployment_confirmation: true # <-- enables deployment confirmation
+          deployment_confirmation_timeout: 60 # <-- sets the timeout to 60 seconds
+```
+
+### Confirming a Deployment 👍
+
+If the user confirms the deployment, the deployment will proceed as normal:
+
+![confirm](./assets/deployment-approved.png)
+
+### Rejecting a Deployment 👎
+
+If the user rejects the deployment, the branch-deploy Action will immediately exit and the `continue` output will not be set to `true`. This will prevent the deployment from proceeding.
+
+![reject](./assets/deployment-rejected.png)
+
+### Timing Out 🕒
+
+If the user does not respond within a set amount of time (configurable, but defaults to 1 minute), the deployment will be automatically rejected. The user will be notified of this outcome.
+
+![timeout](./assets/deployment-timeout.png)
+
+## Demo 📹
+
+View a [demo video](https://github.com/github/branch-deploy/pull/374) of a deployment confirmation in action on the original pull request that introduced this feature.