checks.md

Checks ✅

This feature was originally requested via #73 and further improved in #321 and #362

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:

In this repository, the current ruleset requires the following CI checks:

• test
• acceptance
• 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.

Branch Deploy v12 evaluates the complete paginated check rollup for the selected commit. When the same GitHub App and check name, or the same legacy status context, appears more than once, the newest run is authoritative. A newer pending or failing rerun blocks deployment even if an older run passed. If GitHub returns incomplete, malformed, mismatched, or non-advancing check data, Branch Deploy fails closed and sets commit_status to UNAVAILABLE.

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.

- 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 to any environment

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.

- 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 to any environment

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.

Example 3: Only specific CI checks must pass (required or not)

If you only care about a specific CI check, you can use the checks option with a comma-separated list of checks that must pass. For example, if you only care about the test1 check, you can do the following:

- uses: github/branch-deploy@vX.X.X # replace with the latest version of this Action
  id: branch-deploy
  with:
    checks: 'test1' # we only care about the check named `test1`

This will require that a CI check named test1 must pass before a deployment (to any environment) can start. If the test1 check is in any state other than passing (successful), the deployment will not start. This option will scan all CI checks (required or not) and only the checks that are specified in the checks option will be considered are blocking for deployment. If you have 10 failing CI checks, and only one passing check, and that check is the only one specified in the checks option, the deployment will start.

Please note that just because you can deploy, doesn't always mean you can merge. You should always review the configuration options of this Action and the branch protection (or ruleset) polices within your repository and ensure that they are configured to meet your team's requirements.

If you project has a lot of CI tests, no worries! You could do test1,test2,<etc> to specify multiple checks that must pass.

Example 4: Only certain CI checks are ignored

- uses: github/branch-deploy@vX.X.X # replace with the latest version of this Action
  id: branch-deploy
  with:
    ignored_checks: 'test2,test3' # these two checks are ignored and deployment will be allowed even if they are failing (and required)