go.chromium.org/luci@v0.0.0-20240309015107-7cdc2e660f33/lucicfg/starlark/stdlib/internal/luci/rules/tree_closer.star (about)

     1  # Copyright 2020 The LUCI Authors.
     2  #
     3  # Licensed under the Apache License, Version 2.0 (the "License");
     4  # you may not use this file except in compliance with the License.
     5  # You may obtain a copy of the License at
     6  #
     7  #      http://www.apache.org/licenses/LICENSE-2.0
     8  #
     9  # Unless required by applicable law or agreed to in writing, software
    10  # distributed under the License is distributed on an "AS IS" BASIS,
    11  # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    12  # See the License for the specific language governing permissions and
    13  # limitations under the License.
    14  
    15  """Defines luci.tree_closer(...) rule."""
    16  
    17  load("@stdlib//internal/lucicfg.star", "lucicfg")
    18  load("@stdlib//internal/validate.star", "validate")
    19  load("@stdlib//internal/luci/common.star", "notifiable")
    20  
    21  def _tree_closer(
    22          ctx,  # @unused
    23          *,
    24          name = None,
    25          tree_status_host = None,
    26          failed_step_regexp = None,
    27          failed_step_regexp_exclude = None,
    28          template = None,
    29          notified_by = None):
    30      """Defines a rule for closing or opening a tree via a tree status app.
    31  
    32      The set of builders that are being observed is defined through `notified_by`
    33      field here or `notifies` field in luci.builder(...). Whenever a build
    34      finishes, the builder "notifies" all (but usually none or just one)
    35      luci.tree_closer(...) objects subscribed to it, so they can decide whether
    36      to close or open the tree in reaction to the new builder state.
    37  
    38      Note that luci.notifier(...) and luci.tree_closer(...) are both flavors of
    39      a `luci.notifiable` object, i.e. both are something that "can be notified"
    40      when a build finishes. They both are valid targets for `notifies` field in
    41      luci.builder(...). For that reason they share the same namespace, i.e. it is
    42      not allowed to have a luci.notifier(...) and a luci.tree_closer(...) with
    43      the same name.
    44  
    45      Args:
    46        ctx: the implicit rule context, see lucicfg.rule(...).
    47  
    48        name: name of this tree closer to reference it from other rules. Required.
    49  
    50        tree_status_host: a hostname of the project tree status app (if any) that
    51          this rule will use to open and close the tree. Tree status affects how
    52          CQ lands CLs. See `tree_status_host` in luci.cq_group(...). Required.
    53        failed_step_regexp: close the tree only on builds which had a failing step
    54          matching this regex, or list of regexes.
    55        failed_step_regexp_exclude: close the tree only on builds which don't have
    56          a failing step matching this regex or list of regexes. May be combined
    57          with `failed_step_regexp`, in which case it must also have a failed
    58          step matching that regular expression.
    59        template: a luci.notifier_template(...) to use to format tree closure
    60          notifications. If not specified, and a template `default_tree_status`
    61          is defined in the project somewhere, it is used implicitly by the tree
    62          closer.
    63  
    64        notified_by: builders to receive status notifications from. This relation
    65          can also be defined via `notifies` field in luci.builder(...).
    66      """
    67  
    68      return notifiable.add(
    69          name = name,
    70          props = {
    71              "name": name,
    72              "kind": "luci.tree_closer",
    73              "tree_status_host": validate.string(
    74                  "tree_status_host",
    75                  tree_status_host,
    76                  required = True,
    77              ),
    78              "failed_step_regexp": validate.regex_list(
    79                  "failed_step_regexp",
    80                  failed_step_regexp,
    81              ),
    82              "failed_step_regexp_exclude": validate.regex_list(
    83                  "failed_step_regexp_exclude",
    84                  failed_step_regexp_exclude,
    85              ),
    86          },
    87          template = template,
    88          notified_by = notified_by,
    89      )
    90  
    91  tree_closer = lucicfg.rule(impl = _tree_closer)