Managing pipeline gates

Gates ensure that orchestrations cannot be started in an environment until the gate rule is satisfied.

About this task

A gate is a condition that determines whether an application can run in the environment. A pipeline can have some environments with gates and some without gates. A gate condition is called a rule. You can define a rule type based on the following criteria:
  • Approver gate requires one or more responders to approve an application version before it can run in an environment. Approving a gate rule is considered passing the gate.
    Note: Anyone with access to the pipeline can create gates and be assigned as a responder. Scenarios detailing approval and rejection of application versions by responders are detailed below.
    • If a gate has multiple responders, one approval is sufficient for the application version to pass the gate.
    • If one responder rejects the application version, the application is rejected.
    • If responders both approve and reject the application version, the application is rejected.
    • When you add gates to an environment, all application versions in the affected environment must be approved before a deployment can be started. You can override a failed gate, that is, a rejected application version and you may want to do this when you run applications in a test environment.
  • Metric gate leverages a metric-based system allowing you to automatically stop or advance application versions from being deployed into environments based on set conditions for the rule.
    Note: Using the metric rule type will provide you with visibility on the movement status of application versions and automated governance across your pipeline.
  • Compliance gate enables you to control the deployment of application versions into different environments based on the conditions of the compliance rule.
    Note:
    • Currently under the Compliance gate, you can only create a rule for pull request approval.
    • Compliance rules are enabled only for the following type of applications:
      • Applications added by Jenkins (Legacy) plug-in.
      • Applications added by Jenkins plug-in.
      • Application added by external HCL DevOps Deploy and external IBM DevOps Deploy plug-ins and built using Jenkins. Ensure that the build details are pushed to Velocity using the DevOps Deploy Jenkins publisher or pipeline plug-ins.
  • Status gate allows you to define the statuses of a snapshot version in a Continuous Delivery (CD) application like DevOps Deploy and automatically stop or advance application versions from being deployed into different environments by matching the defined statuses with the actual statuses of the snapshot version.

    For example, when the two statuses functional_testing and regression_testing are added in the Status gate rule, the following scenarios illustrate when the gate will pass or fail:

    Scenario 1: Status of a snapshot version in a CD application is empty.

    In this scenario, the gate looks for both the functional_testing and regression_testing status in the snapshot version but the synced snapshot version will neither have functional_testing or regression_testing, so the gate will fail.

    Scenario 2: Status of a snapshot version in a CD application is having one of the statuses added in the Status gate rule.

    In this scenario, the gate looks for both the functional_testing and regression_testing status in the snapshot version, but the synced snapshot version will have either functional_testing or regression_testing, so the gate will fail.

    Scenario 3: Status of a snapshot version in a CD application is having both the status added in the Status gate rule.

    In this scenario, the gate looks for both the functional_testing and regression_testing status in the snapshot version, the synced snapshot version will have both functional_testing and regression_testing, so the gate will pass.

    Scenario 4: Status of a snapshot version in a CD application is having both statuses and other additional status.

    In this scenario, the gate looks for both the functional_testing and regression_testing status in the snapshot version, the synced snapshot version will have functional_testing, regression_testing, and other additional status so the gate will pass.

    Scenario 5: Status of a snapshot version in a CD application is having one out of two statuses and other additional status.

    In this scenario, the gate looks for both the functional_testing and regression_testing status in the snapshot version, but the synced snapshot version will have either functional_testing or regression_testing, and other additional status so the gate will fail.

    Note:
    • Currently the Status gate is not enabled for hybrid Continuous Integration/Continuous Deployment (CI/CD) pipelines. If you are using Status gates in hybrid CI/CD pipelines the gates will always fail.
    • Status gate is enabled only for the applications added by the following plug-in versions of HCL DevOps Deploy and IBM DevOps Deploy:
      • HCL DevOps Deploy 4.0.3 or later.
      • IBM DevOps Deploy 4.0.3 or later.

Procedure

  1. For the environment where you want to add a gate, click stage context menu and select Add gate, and then perform the following steps.
    Note: For the environment where you want to modify a gate, click stage context menu and select Edit gate, and then complete the following steps.
    1. In the Add gate window, click New Rule.
      To use an existing rule, click Existing Rules.
    2. In the Rule Type field, select Approver, Metric, Compliance, or Status. Based on the Rule Type selected, use the following tables to add Approver, Metric, Compliance, or Status gates to environments.
      Table 1. Approver gate
      "Approver" Add gate option Value / action
      Name your new rule Enter a name for the rule.
      Add Approver(s) In the list, select responders.
      Add Rule Click to add gate to the environment, which is indicated by the Gate icon on the environment label. To view gate rules, click the Gate icon. A Gate status icon is added to the applications in the environment.
      Note: Initially, the Gate status is indicated by a vertical gray bar located to the left of the application version. If all application versions are approved, the gate is passed and the Gate status is a green bar. If application versions are rejected, the Gate status is a red bar.
      Approver Rules statuses Under the Edit environment Gate Rules on the right side of the Add gate window, you can view the statuses of the Metric rules and Approver rules. Under the Approver rules, select the Send email alert to any user that requires manual approval checkbox to receive email notification for approving the approver gates. The email notification is sent to all approver gate approvers. The approver gates approval email notification contains the Stage Name, Approver Gate Name, Application Name, and Version Name of the application for which the approval is requested.
      Save Click to populate the rule on the gate.
      Send email notification to any user that requires manual approval select the checkbox to send the e-mail notification for the designated approvers.
      Table 2. Metric gate
      "Metric" Add gate option Value / action
      Name your new rule Enter a name for the rule.
      Description Enter a description for the rule.
      Metric Type Select the required metric in the list from the following: Coverage by Branch, Coverage by Function, Coverage by Line, Functional Tests, Static Code Analysis, Unit Tests, Container Vulnerabilities, or Application Vulnerabilities. Descriptions for each Metric Type can be found here.
      Data Set Select the required metric data set.
      Field Select the required field from the list.
      Note: The field is based on the Metric Type used for the metric rule and will be dynamically populated with selections associated with the metric.
      For example, if Application Vulnerabilities is selected, then Blocker will be the criteria measure for the gate.
      Operator Select the required operator from the list.
      Note: The operator is based on the Field that was selected and will be dynamically populated with selections suitable to the field. For example, if Blocker is the field, then the following list will be the available operators: =, !=, >, or <.
      Value Select the required value from the list.
      Note: The required value is entered based on the field and operator. For example, a value of zero indicating Blocker = 0 as the rule to pass the gate.
      Occurrence period Select the required occurrence period for the rule from the following list: None, Minutes, Hours, Days, Weeks, or Months.
      Duration Enter the duration for occurrence period of the rule.
      Add Rule Click to add gate to the environment, which is indicated by the Gate icon on the environment label. To view gate rules, click the Gate icon. A Gate status icon is added to the applications in the environment.
      Note: If all the application versions satisfies the added Metric rule, the gate is passed and the Gate status is a green bar. If application versions are rejected, the Gate status is a red bar.
      Metric Rules statuses Under the Edit environment Gate Rules on the right side of the Add gate window, you can view the statuses of the Metric Rules.
      Save Click to populate the rule on the gate.
      Note: For the above example of Blocker = 0, you may notice all the versions have a red bar indicating each had a blocker because of a failure with security scan.
      Table 3. Compliance gate
      "Compliance" Add gate option Value / action
      Name your new rule Enter a name for the rule.
      Description Enter a description for the rule.
      Resource Type Select the resource type from the list.
      Field Select the required field from the list.
      Operator Select the required operator from the list.
      Note: The operator is based on the Field that was selected and will be dynamically populated with selections suitable to the field.
      Value Select the required value from the list.
      Note: The required value is entered based on the field and operator.
      Add Rule Click to add gate to the environment, which is indicated by the Gate icon on the environment label. To view gate rules, click the Gate icon. A Gate status icon is added to the applications in the environment.
      Note: If all the application versions satisfies the added Compliance rule, the gate is passed and the Gate status is a green bar. If application versions are rejected, the Gate status is a red bar.
      Compliance Rules statuses Under the Edit environment Gate Rules on the right side of the Add gate window, you can view the statuses of the Compliance Rules.
      Save Click to populate the rule on the gate.
      Table 4. Status gate
      "Status" Add gate option Value / action
      Name your new rule Enter a name for the rule.
      Description Enter a description for the rule.
      Status (Comma Separated List) Add the statuses which you want to match with the snapshot version in a CD application. You can add multiple statuses by separating them with a comma. Note: status names are case sensitive, enter the exact name in the snapshot version, if not the gates will fail.
      Add Rule Click to add gate to the environment, which is indicated by the Gate icon on the environment label. To view gate rules, click the Gate icon. A Gate status icon is added to the applications in the environment.
      Note: If all the status defined in the status rule matches the status added in the snapshot version, the gate is passed and Gate status is a green bar. If the statuses does not match the gates are failed, the Gate status is a red bar.
      Status Rules statuses Under the Edit environment Gate Rules on the right side of the Add gate window, you can view the statuses of the Status Rules.
      Save Click to populate the rule on the gate.
    3. In the Add gate window, on the right side, you can hover over a rule and click Remove rule to delete the individual rules.
  2. In the Environment stage, click the Gate icon to view the gate rules.
    You can see the number of rules and approvers for each gate.
  3. In the Pipeline window, click the Gate status icon for the application version with the gate to open Version Rules window.
    You can see the status of the gates and designated approvers can approve or reject the approver gate rule.
  4. On the Version Rules window, click Approve or Reject and then click Save to approve or reject the approver gate rule.
    Note: If you are an approver for multiple rules, you can approve all or some of them and reject others. If you are not a designated responder, you can neither approve nor reject the gate rule.
  5. For the environment where you want to delete a gate, click stage context menu and select Delete gate.

What to do next

Run a deployment for a pipeline stage.