Merge pull request #244 from github/checks-input-docs

Checks input docs

README.md

@@ -274,6 +274,7 @@ As seen above, we have two steps. One for a noop deploy, and one for a regular d
 | `outdated_mode` | `false` | `"strict"` | The mode to use for determining if a branch is up-to-date or not before allowing deployments. This option is closely related to the `update_branch` input option above. There are three available modes to choose from: `pr_base`, `default_branch`, or `strict`. The default is `strict` to help ensure that deployments are using the most up-to-date code. Please see the [documentation](docs/outdated_mode.md) for more details. |
 | `required_contexts` | `false` | `"false"` | Manually enforce commit status checks before a deployment can continue. Only use this option if you wish to manually override the settings you have configured for your branch protection settings for your GitHub repository. Default is "false" - Example value: "context1,context2,context3" - In most cases you will not need to touch this option |
 | `skip_ci` | `false` | `""` | A comma separated list of environments that will not use passing CI as a requirement for deployment. Use this option to explicitly bypass branch protection settings for a certain environment in your repository. Default is an empty string `""` - Example: `"development,staging"` |
+| `checks` | `false` | `"all"` | This input defines how the branch-deploy Action will handle the status of CI checks on your PR/branch before deployments can continue. `"all"` requires that all CI checks must pass in order for a deployment to be triggered. `"required"` only waits for required CI checks to be passing. View the [documentation](docs/checks.md) for more details. |
 | `skip_reviews` | `false` | `""` | A comma separated list of environment that will not use reviews/approvals as a requirement for deployment. Use this options to explicitly bypass branch protection settings for a certain environment in your repository. Default is an empty string `""` - Example: `"development,staging"` |
 | `allow_forks` | `false` | `"true"` | Allow branch deployments to run on repository forks. If you want to harden your workflows, this option can be set to false. Default is "true" |
 | `admins` | `false` | `"false"` | A comma separated list of GitHub usernames or teams that should be considered admins by this Action. Admins can deploy pull requests without the need for branch protection approvals. Example: "monalisa,octocat,my-org/my-team" |

__tests__/functions/help.test.js

@@ -45,7 +45,8 @@ const defaultInputs = {
   draft_permitted_targets: '',
   admins: 'false',
   permissions: ['write', 'admin', 'maintain'],
-  allow_sha_deployments: false
+  allow_sha_deployments: false,
+  checks: 'all'
 }
 
 test('successfully calls help with defaults', async () => {
@@ -79,7 +80,8 @@ test('successfully calls help with non-defaults', async () => {
     draft_permitted_targets: 'development',
     admins: 'monalisa',
     permissions: ['write', 'admin', 'maintain'],
-    allow_sha_deployments: true
+    allow_sha_deployments: true,
+    checks: 'all'
   }
 
   expect(await help(octokit, context, 123, inputs))
@@ -112,7 +114,8 @@ test('successfully calls help with non-defaults', async () => {
     draft_permitted_targets: 'development',
     admins: 'monalisa',
     permissions: ['write', 'admin', 'maintain'],
-    allow_sha_deployments: false
+    allow_sha_deployments: false,
+    checks: 'required'
   }
 
   expect(await help(octokit, context, 123, inputs))

action.yml

@@ -98,7 +98,7 @@ inputs:
     required: false
     default: ""
   checks:
-    description: 'The mode to use for CI checks. "all" requires all checks to pass no matter what, "required" only waits for required checks.'
+    description: 'This input defines how the branch-deploy Action will handle the status of CI checks on your PR/branch before deployments can continue. `"all"` requires that all CI checks must pass in order for a deployment to be triggered. `"required"` only waits for required CI checks to be passing. View the documentation (docs/checks.md) for more details.'
     required: false
     default: "all"
   skip_reviews:

docs/checks.md

@@ -0,0 +1,54 @@
+# Checks ✅
+
+> This feature was originally requested via [#73](https://github.com/github/branch-deploy/issues/73)
+
+The branch-deploy Action contains a useful input option to help give developers more control over how CI checks are handled during the deployment process. Some teams may have very strict controls over deployments and require **all status checks** to pass before a deployment can start. In this case, all CI checks must pass and that includes required, or non-required checks. Other teams may have a more relaxed approach and only require certain checks to pass before a deployment can start. This is where the `checks` input option comes in handy.
+
+## Required CI Checks
+
+First, let's explain what a "required" CI check is in case you're not familiar. A required CI check is a check that must pass before a pull request can be merged. This is a setting that can be configured in the repository settings under the "Branches" section. This section is shown in the screenshot below:
+
+![required-ci-checks](assets/required-ci-checks.png)
+
+> This example came directly from this respository's settings
+
+So in this particular repository, the following CI checks are required:
+
+- `test`
+- `package-check`
+- `lint`
+- `actions-config-validation`
+
+Any other CI checks that run on a pull request are not required and are considered non-required checks.
+
+## Using the `checks` Input Option
+
+This section will contain a few examples of how you can use the `checks` option
+
+### Example 1: All CI Checks Must Pass
+
+This example shows how you can use the `checks` option to require all CI checks to pass before a deployment can start. This is the **default** behavior of the Action if you do not specify the `checks` option.
+
+```yaml
+- name: branch-deploy
+  uses: github/branch-deploy@vX.X.X # replace with the latest version of this Action
+  id: branch-deploy
+  with:
+    checks: "all" # all CI checks (required or not) must pass before a deployment can start
+```
+
+### Example 2: Only Required CI Checks Must Pass
+
+This example shows how you can use the `checks` option to require only the **required** CI checks to pass before a deployment can start. This is useful if you have non-required checks that you don't want to block a deployment.
+
+```yaml
+- name: branch-deploy
+  uses: github/branch-deploy@vX.X.X # replace with the latest version of this Action
+  id: branch-deploy
+  with:
+    checks: "required" # only required CI checks must pass before a deployment can start
+```
+
+The screenshot below demonstrates how this option works in a real-world scenario. You can see how there are two CI checks defined on the pull request. One is called `test1` which is **required** and **passing**. The other is called `test2` which is **not required** and **failing**. Since the `checks` option is set to `required`, the deployment will start because the required check is passing and is the only status check taken into consideration for a deployment.
+
+![required-ci-checks-example](assets/required-ci-checks-example.png)

src/functions/help.js

@@ -27,6 +27,13 @@ export async function help(octokit, context, reactionId, inputs) {
     required_contexts_message = `There are required contexts designated for this Action`
   }
 
+  var checks_message = defaultSpecificMessage
+  if (inputs.checks.trim() === 'required') {
+    checks_message = `Only required CI checks must pass before a deployment can be requested`
+  } else {
+    checks_message = `All CI checks must pass before a deployment can be requested`
+  }
+
   var skip_ci_message = defaultSpecificMessage
   if (inputs.skipCi.trim() !== '') {
     skip_ci_message = `This Action will not require passing CI for the environments specified`
@@ -181,6 +188,7 @@ export async function help(octokit, context, reactionId, inputs) {
     inputs.allowForks === 'true' ? 'run' : 'not run'
   } on forked repositories
   - \`skipCi: ${inputs.skipCi}\` - ${skip_ci_message}
+  - \`checks: ${inputs.checks}\` - ${checks_message}
   - \`skipReviews: ${inputs.skipReviews}\` - ${skip_reviews_message}
   - \`draft_permitted_targets: ${
     inputs.draft_permitted_targets