Creating policies

CloudBees SDM is a preview, with early access for select preview members. Product features and documentation are frequently updated. If you find an issue or have a suggestion, please contact CloudBees Support. Learn more about the preview program.

Policies enable engineering managers and leaders to define rules related to the development process of a product or feature. Organization-wide policies provide easy to create global policies to define common best-practices or rules matching their software delivery methodology. A policy applies to the organization profile associated with your admin user profile.

Creating a policy involves three steps:

  1. Naming the policy.

  2. Creating a rule for the policy.

  3. Defining the policy action.

Only an administrator for CloudBees SDM can create, edit, or modify policies and rules using the policy editor. Users who are non-administrators can then view the results of policies from generated notifications when a policy’s rules are violated.

Policy rules and actions

Each policy has a rule and associated actions. Rules can enforce specific steps that drive best practices, compliance, or governance requirements for the process, which help ensure higher quality, more stable software for the customer. If a policy has matches, actions associated with the policy are triggered. For example, a status label defined in the action can appear on the Pull requests screen when conditions for the policy are met.

Sample policies and examples are included with CloudBees SDM and can be used to create your own policies.

To create a policy, you have to define the rules and actions taken if a policy has matches. Rules are defined using the Rules tab of the policy editor.

Naming a policy

The first step is to name the policy and provide a description:

  1. From Products, select Policies.

  2. Select Create policy.

  3. Enter a policy name and, optionally, a description. Select Save changes.

Creating a rule for the policy

One a policy has been named, it needs a rule and an action. A policy rule is made up two parts: the set of data that you want apply the policy to, and the criteria that will be applied to determine whether the data matches the policy.

Rules are created from three components:

Data type

Determines the type of data to which the policy applies and depends upon the services integrated with CloudBees SDM.

Target filter (optional)

Filters the data to be evaluated. By default, the policy will be evaluated for all instances of the given data type. If a target filter is specified, the policy is only evaluated for instances for which the target filter evaluates to true.

Criteria

Defines what status must be met for the actions associated with the policy to be triggered. The actions are triggered for instances where the expression defined by the criteria evaluates to true.

Data types

The set of data is specified by giving the type of data to which the policy should be applied, such as GithubPullRequest. Each service that is integrated in CloudBees SDM adds new data types that can be used in queries for both policies and reports. For information about specific data types, refer to the Policy targets section.

The target data set can be constrained further by specifying a filter. For example, use state = 'OPEN' for the type GithubPullRequest to indicate that the policy should only be applied to open pull requests.

Criteria and target filter

The criteria is an expression that is evaluated for every data entity in the target data set. The result of true or false is stored and policy actions performed when the result is true. The expression may use fields on the given data type or follow relationships to other, related, data types. For example, the criteria pullRequestReviews.size() = 0 and reviewRequests.size() = 0 evaluates to true when a pull request has no reviews and there are no reviews requested.

The target filter and criteria are both defined using the SDM query language.

Creating a policy rule

To create a policy rule:

  1. Select a policy and then select the Rule tab.

  2. Select a data type from Data type.

  3. Optional: Enter a filter in Target filter.

  4. Enter criteria in the Criteria text box.

  5. Select Save changes.

Once the Rule is defined, you need to add actions to determine what happens when the policy conditions are met.

Defining policy actions

Once a policy is created, the next step is to establish actions that happen when the policy is triggered. Each policy can have one or more actions.

Currently, only status labels can be assigned as an action. A status label appears as colored text next to an item that matches a policy’s rules. Status labels use three colors:

  • Red: Needs immediate attention. Work is blocked.

  • Yellow. Needs attention soon. Work might be blocked.

  • Green: Requires action. Work is not blocked.

The Repositories screen uses predefined status labels.

To define an action for a policy:

  1. Select the Policy tab and then select the policy you wish to edit.

  2. Select the policy’s Actions tab.

  3. Select Add action and then select Status label.

  4. Select an option from Label type: Needs attention, Needs action, or Needs attention soon.

  5. Enter a Label name.

  6. Select Save changes.

Once an action is created, you can toggle it on or off using the slider. The slider is blue when an action is active and light gray when inactive.

Viewing the results of policy actions

Where the status labels generated by the policy actions are visible depends on the data type specified in the policy. For GitHub pull requests, they are visible by selecting a product and then Pull requests.