buildbucket/proto/notification.proto

// Copyright 2018 The Swarming Authors. All rights reserved.
// Use of this source code is governed by the Apache v2.0 license that can be
// found in the LICENSE file.

syntax = "proto3";

package buildbucket.v2;

option go_package = "go.chromium.org/luci/buildbucket/proto;buildbucketpb";

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

// Configuration for per-build notification. It's usually set by the caller on
// each ScheduleBuild request.
message NotificationConfig {
  // Target Cloud PubSub topic.
  // Usually has format "projects/{cloud project}/topics/{topic name}".
  //
  // The PubSub message data schema is defined in `PubSubCallBack` in this file.
  //
  // The legacy schema is:
  //     {
  //      'build': ${BuildMessage},
  //      'user_data': ${NotificationConfig.user_data}
  //      'hostname': 'cr-buildbucket.appspot.com',
  //    }
  // where the BuildMessage is
  // https://chromium.googlesource.com/infra/infra.git/+/b3204748243a9e4bf815a7024e921be46e3e1747/appengine/cr-buildbucket/legacy/api_common.py#94
  //
  // Note: The legacy data schema is deprecated. Only a few old users are using
  // it and will be migrated soon.
  //
  // <buildbucket-app-id>@appspot.gserviceaccount.com must have
  // "pubsub.topics.publish" and "pubsub.topics.get" permissions on the topic,
  // where <buildbucket-app-id> is usually "cr-buildbucket."
  string pubsub_topic = 1;

  // Will be available in PubSubCallBack.user_data.
  // Max length: 4096.
  bytes user_data = 2;
}

// BuildsV2PubSub is the "builds_v2" pubsub topic message data schema.
// Attributes of this pubsub message:
// - "project"
// - "bucket"
// - "builder"
// - "is_completed" (The value is either "true" or "false" in string.)
// - "version" (The value is "v2". To help distinguish messages from the old `builds` topic)
message BuildsV2PubSub {
  // Contains all field except large fields
  Build build = 1;
  // A Compressed bytes in proto binary format of buildbucket.v2.Build where
  // it only contains the large build fields - build.input.properties,
  // build.output.properties and build.steps.
  bytes build_large_fields = 2;

  // The compression method the above `build_large_fields` uses. By default, it
  // is ZLIB as this is the most common one and is the built-in lib in many
  // programming languages.
  Compression compression = 3;
}

// PubSubCallBack is the message data schema for the ad-hoc pubsub notification
// specified per ScheduleBuild request level.
// Attributes of this pubsub message:
// - "project"
// - "bucket"
// - "builder"
// - "is_completed" (The value is either "true" or "false" in string.)
// - "version" (The value is "v2". To help distinguish messages from the old `builds` topic)
message PubSubCallBack {
  // Buildbucket build
  BuildsV2PubSub build_pubsub = 1;

  // User-defined opaque blob specified in NotificationConfig.user_data.
  bytes user_data = 2;
}