go.chromium.org/luci@v0.0.0-20240309015107-7cdc2e660f33/deploy/api/modelpb/deployment.proto

// Copyright 2022 The LUCI Authors.
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//      http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

syntax = "proto3";

package deploy.model;

option go_package = "go.chromium.org/luci/deploy/api/modelpb";

import "google/protobuf/duration.proto";

// Identifier of a deployment: a reference to its config location.
//
// A deployment is located in some directory of a git repository on `HEAD` ref.
//
// The directory path has two segments: the path to the root of the
// configuration tree, and the path to the particular configuration within this
// tree.
message DeploymentID {
  // Hostname of the GoB server with the IaC repository, e.g. "chrome-internal".
  string repo_host = 1;
  // Name of the IaC repository relative to the host, e.g. "infradata/gae".
  string repo_name = 2;
  // Path to the root of the IaC config tree in the repository, e.g. ".".
  string repo_path = 3;
  // Path to the directory inside the IaC configs, e.g. "apps/luci-deploy/prod".
  string config_path = 4;
}


// Deployment as defined in the IaC repo.
message Deployment {
  // The stable identifier of the deployment based on the config location.
  DeploymentID id = 1;

  // The revision of the HEAD of IaC repository with the deployment.
  //
  // Can be obtained with `git rev-parse HEAD`. Moves frequently.
  string repo_rev = 2;

  // The revision of the deployment config directory.
  //
  // Can be obtained `git log --pretty=tformat:"%H" -n1 <config_path>`. If it
  // changes, the deployment most like is changing too.
  string config_rev = 3;

  // Configuration for the deployment system itself, as defined in the IaC repo.
  //
  // Applies to all assets associated with this deployment.
  DeploymentConfig config = 4;

  // Details of the commit matching `config_rev`.
  CommitDetails latest_commit = 5;
}


// Deployment configuration, as defined in the IaC repo.
message DeploymentConfig {
  // How long the actuation can run before it is considered crashed.
  //
  // Default is 20 min.
  google.protobuf.Duration actuation_timeout = 1;

  // Who to notify on noteworthy events.
  //
  // Various asset state transitions emit 0 or more events per transition. For
  // each event kind `notifications` define a set of destinations to send it
  // to. During a state transition, all emitted events are bucketed by their
  // destination, then redundant events are trimmed (e.g. if a single
  // destination is getting ACTUATION_FIXED and ACTUATION_SUCCEEDED events, only
  // ACTUATION_FIXED will be retained, since it makes little sense to send
  // two success notifications to the same destination at the same time).
  message Notification {
    // Types of events to notify on.
    enum Event {
      EVENT_UNSPECIFIED = 0;

      // An actuation is starting.
      //
      // Always emitted regardless of any prior history.
      ACTUATION_STARTING  = 1;

      // An actuation has finished successfully.
      //
      // Always emitted regardless of any prior history.
      ACTUATION_SUCCEEDED = 2;

      // An actuation failed, perhaps after several retries.
      //
      // First few failures (below `consecutive_failures` threshold) will *not*
      // result in an event. Every consecutive failure after that will result
      // in an event.
      ACTUATION_FAILED = 3;

      // An actuation succeeded after a series of failures.
      //
      // Emitted if the actuation succeeded after >= `consecutive_failures`
      // consecutive failures. Overrides ACTUATION_SUCCEEDED if emitted by the
      // same state transition.
      ACTUATION_FIXED = 4;
    }
    repeated Event events = 1;

    // List of emails to send notifications to.
    repeated string emails = 2;

    // List of Google Chat spaces to send notifications to.
    message ChatSpace {
      // Space ID e.g. "AAAA9ulaM5M", can be extracted from the Space URL.
      //
      // The chat app needs to be added into the space first. Search for it
      // using "LUCI Deploy" title.
      string id = 1;
    }
    repeated ChatSpace chat_spaces = 3;

    // Consecutive failures threshold for ACTUATION_FAILED and ACTUATION_FIXED.
    //
    // First few failures (below the threshold) will *not* result in
    // a notification. This is useful to avoid spamming on flaky failures
    // resolved by automatic retries.
    int32 consecutive_failures = 4;
  }
  repeated Notification notifications = 2;
}


// Details of an IaC repo commit, to show in the UI.
message CommitDetails {
  // Author name, as git understands it.
  string author_name = 1;
  // Author email, as git understands it.
  string author_email = 2;
  // Full commit message, including subject and footers.
  string commit_message = 3;
}