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/+/master/luci_notify/doc/email_templates.md)

syntax = "proto3";

package notify;

option go_package = "config";

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

// 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;
}

// 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;
}

// Notification specifies the triggers to watch for and send
// notifications on. It also specifies email recipients.
//
// Next ID: 8.
message Notification {
  // Email is a message representing a set of mail recipients (email
  // addresses).
  message Email {
    // Recipients is a list of email addresses to notify.
    repeated string recipients = 1;
  }

  // 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;
  }

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

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

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

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

  // 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 recieve multiple emails.
  //
  // Optional.
  Blamelist notify_blamelist = 6;
}

// 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;
}