luci_notify/api/config/notify.proto

// Copyright 2017 The LUCI Authors. All rights reserved.
// Use of this source code is governed under the Apache License, Version 2.0
// that can be found in the LICENSE file.

// Schema for project-level configuration in luci-notify.

// luci-notify users can define custom email templates,
// see
// [email_templates.md](https://chromium.googlesource.com/infra/luci/luci-go/+/HEAD/luci_notify/doc/email_templates.md)

syntax = "proto3";

package notify;

import "go.chromium.org/luci/buildbucket/proto/build.proto";
import "go.chromium.org/luci/buildbucket/proto/common.proto";
import "go.chromium.org/luci/buildbucket/proto/step.proto";
import "go.chromium.org/luci/common/proto/options.proto";

option go_package = "config";
option (luci.file_metadata) = {
  doc_url: "https://luci-config.appspot.com/schemas/projects:luci-notify.cfg"
};

// ProjectConfig is a luci-notify configuration for a particular project.
message ProjectConfig {
  // Notifiers is a list of Notifiers which watch builders and send
  // notifications for this project.
  repeated Notifier notifiers = 1;

  // If false, then LUCI-Notify won't actually close trees, only log what
  // actions it would have taken.
  bool tree_closing_enabled = 2;
}

// Notifier contains a set of notification configurations (which specify
// triggers to send notifications on) and a set of builders that will be
// watched for these triggers.
message Notifier {
  // Name is an identifier for the notifier which must be unique within a
  // project.
  //
  // Name must additionally match ^[a-z\-]+$, meaning it must only
  // use an alphabet of lowercase characters and hyphens.
  //
  // Required.
  string name = 1;

  // Notifications is a list of notification configurations.
  repeated Notification notifications = 2;

  // Builders is a list of buildbucket builders this Notifier should watch.
  repeated Builder builders = 3;

  // A list of tree closing rules to execute for this notifier.
  repeated TreeCloser tree_closers = 4;
}

// Notification specifies the triggers to watch for and send
// notifications on. It also specifies email recipients.
//
// Next ID: 13.
message Notification {
  reserved 8;

  // Email is a message representing a set of mail recipients.
  message Email {
    // Recipients is a list of email addresses to notify.
    repeated string recipients = 1;

    // A list of rotations, for each of which we should notify the currently
    // active member.
    repeated string rotation_urls = 3;

    reserved 2;
  }

  // Blamelist is a message representing configuration for notifying the
  // blamelist.
  message Blamelist {
    // A list of repositories which we are allowed to be included as part of the
    // blamelist. If unset, a blamelist will be computed based on a Builder's
    // repository field. If set, however luci-notify computes the blamelist for
    // all commits related to a build (which may span multiple repositories)
    // which are part of repository in this repository whitelist.
    //
    // Repositories should be valid Gerrit/Gitiles repository URLs, such as
    // https://chromium.googlesource.com/chromium/src
    //
    // Optional.
    repeated string repository_whitelist = 1;
  }

  // Deprecated. Notify on each build success.
  bool on_success = 1;

  // Deprecated. Notify on each build failure.
  bool on_failure = 2;

  // Deprecated. Notify on each build status different than the previous one.
  bool on_change = 3;

  // Deprecated. Notify on each build failure unless the previous build was a
  // failure.
  bool on_new_failure = 7;

  // Notify on each build with a specified status.
  repeated buildbucket.v2.Status on_occurrence = 9;

  // Notify on each build with a specified status different than the previous
  // one.
  repeated buildbucket.v2.Status on_new_status = 10;

  // Notify only on builds which had a failing step matching this regular
  // expression. Mutually exclusive with "on_new_status".
  string failed_step_regexp = 11;

  // Notify only on builds which don't have a failing step matching this regular
  // expression. May be combined with "failed_step_regexp", in which case it
  // must also have a failed step matching that regular expression. Mutually
  // exclusive with "on_new_status".
  string failed_step_regexp_exclude = 12;

  // Email is the set of email addresses to notify.
  //
  // Optional.
  Email email = 4;

  // Refers to which project template name to use to format this email.
  // If not present, "default" will be used.
  //
  // Optional.
  string template = 5;

  // NotifyBlamelist specifies whether to notify the computed blamelist for a
  // given build.
  //
  // If set, this notification will be sent to the blamelist of a build. Note
  // that if this is set in multiple notifications pertaining to the same
  // builder, the blamelist may receive multiple emails.
  //
  // Optional.
  Blamelist notify_blamelist = 6;
}

// TreeCloser represents an action which closes a tree, by interfacing with an
// instance of the tree-status app.
message TreeCloser {
  // The hostname of the tree-status instance which this rule opens and closes.
  string tree_status_host = 1;

  // Close the tree only on builds which had a failing step matching this
  // regular expression.
  string failed_step_regexp = 2;

  // Close the tree only on builds which don't have a failing step matching this
  // regular expression. May be combined with "failed_step_regexp", in which
  // case it must also have a failed step matching that regular expression.
  string failed_step_regexp_exclude = 3;

  // Refers to which project template name to use to format this email.
  // If not present, "default_tree_status" will be used.
  string template = 4;
}

// Builder references a buildbucket builder in the current project.
message Builder {
  // Bucket is the buildbucket bucket that the builder is a part of.
  //
  // Required.
  string bucket = 1;

  // Name is the name of the buildbucket builder.
  //
  // Required.
  string name = 2;

  // Repository is the git repository associated with this particular builder.
  //
  // The repository should look like a URL, e.g.
  // https://chromium.googlesource.com/src
  //
  // Currently, luci-notify only supports Gerrit-like URLs since it checks
  // against gitiles commits, so the URL's path (e.g. "src" in the above
  // example) should map directly to a Gerrit project.
  //
  // Builds attached to the history of this repository will use this
  // repository's git history to determine the order between two builds for the
  // OnChange notification.
  //
  // Optional.
  //
  // If not set, OnChange notifications will derive their notion of
  // "previous" build solely from build creation time, which is potentially
  // less reliable.
  string repository = 3;
}

// Notifications encapsulates a list of notifications as a proto so code for
// storing it in the datastore may be generated.
message Notifications {
  // Notifications is a list of notification configurations.
  repeated Notification notifications = 1;
}

// A collection of landed Git commits hosted on Gitiles.
message GitilesCommits {
  // The Gitiles commits in this collection.
  repeated buildbucket.v2.GitilesCommit commits = 1;
}

// Input to an email template.
message TemplateInput {
  // Buildbucket hostname, e.g. "cr-buildbucket.appspot.com".
  string buildbucket_hostname = 1;
  // The completed build.
  buildbucket.v2.Build build = 2;
  // State of the previous build in this builder.
  buildbucket.v2.Status old_status = 3;
  // The failed steps that passed the given regexes (see the fields
  // "failed_step_regexp" and "failed_step_regexp_exclude" above). If that field
  // wasn't supplied, this will be empty.
  repeated buildbucket.v2.Step matching_failed_steps = 4;
}