data.proto

// Copyright 2020 Google LLC
//
// 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 google.events.cloud.cloudbuild.v1;

import "google/protobuf/duration.proto";
import "google/protobuf/timestamp.proto";

option csharp_namespace = "Google.Events.Protobuf.Cloud.CloudBuild.V1";
option php_namespace = "Google\\Events\\Cloud\\CloudBuild\\V1";
option ruby_package = "Google::Events::Cloud::CloudBuild::V1";

// Build event data for Google Cloud Platform API operations.
message BuildEventData {
  // Possible status of a build or build step.
  enum Status {
    // Status of the build is unknown.
    STATUS_UNKNOWN = 0;

    // Build or step is queued; work has not yet begun.
    QUEUED = 1;

    // Build or step is being executed.
    WORKING = 2;

    // Build or step finished successfully.
    SUCCESS = 3;

    // Build or step failed to complete successfully.
    FAILURE = 4;

    // Build or step failed due to an internal cause.
    INTERNAL_ERROR = 5;

    // Build or step took longer than was allowed.
    TIMEOUT = 6;

    // Build or step was canceled by a user.
    CANCELLED = 7;

    // Build was enqueued for longer than the value of `queue_ttl`.
    EXPIRED = 9;
  }

  // Unique identifier of the build.
  string id = 1;

  // ID of the project.
  string project_id = 16;

  // Status of the build.
  Status status = 2;

  // Customer-readable message about the current status.
  string status_detail = 24;

  // The location of the source files to build.
  Source source = 3;

  // The operations to be performed on the workspace.
  repeated BuildStep steps = 11;

  // Results of the build.
  Results results = 10;

  // Time at which the request to create the build was received.
  google.protobuf.Timestamp create_time = 6;

  // Time at which execution of the build was started.
  google.protobuf.Timestamp start_time = 7;

  // Time at which execution of the build was finished.
  //
  // The difference between finish_time and start_time is the duration of the
  // build's execution.
  google.protobuf.Timestamp finish_time = 8;

  // Amount of time that this build should be allowed to run, to second
  // granularity. If this amount of time elapses, work on the build will cease
  // and the build status will be `TIMEOUT`.
  google.protobuf.Duration timeout = 12;

  // A list of images to be pushed upon the successful completion of all build
  // steps.
  //
  // The images are pushed using the builder service account's credentials.
  //
  // The digests of the pushed images will be stored in the `Build` resource's
  // results field.
  //
  // If any of the images fail to be pushed, the build status is marked
  // `FAILURE`.
  repeated string images = 13;

  // TTL in queue for this build. If provided and the build is enqueued longer
  // than this value, the build will expire and the build status will be
  // `EXPIRED`.
  //
  // The TTL starts ticking from create_time.
  google.protobuf.Duration queue_ttl = 40;

  // Artifacts produced by the build that should be uploaded upon
  // successful completion of all build steps.
  Artifacts artifacts = 37;

  // Google Cloud Storage bucket where logs should be written (see
  // [Bucket Name
  // Requirements](https://cloud.google.com/storage/docs/bucket-naming#requirements)).
  // Logs file names will be of the format `${logs_bucket}/log-${build_id}.txt`.
  string logs_bucket = 19;

  // A permanent fixed identifier for source.
  SourceProvenance source_provenance = 21;

  // The ID of the `BuildTrigger` that triggered this build, if it
  // was triggered automatically.
  string build_trigger_id = 22;

  // Special options for this build.
  BuildOptions options = 23;

  // URL to logs for this build in Google Cloud Console.
  string log_url = 25;

  // Substitutions data for `Build` resource.
  map<string, string> substitutions = 29;

  // Tags for annotation of a `Build`. These are not docker tags.
  repeated string tags = 31;

  // Secrets to decrypt using Cloud Key Management Service.
  repeated Secret secrets = 32;

  // Stores timing information for phases of the build. Valid keys
  // are:
  //
  // * BUILD: time to execute all build steps
  // * PUSH: time to push all specified images.
  // * FETCHSOURCE: time to fetch source.
  //
  // If the build does not specify source or images,
  // these keys will not be included.
  map<string, TimeSpan> timing = 33;
}

message Source {
  // Location of source.
  oneof source {
    // If provided, get the source from this location in Google Cloud Storage.
    StorageSource storage_source = 2;

    // If provided, get the source from this location in a Cloud Source
    // Repository.
    RepoSource repo_source = 3;
  }
}

// Location of the source in an archive file in Google Cloud Storage.
message StorageSource {
  // Google Cloud Storage bucket containing the source (see
  // [Bucket Name
  // Requirements](https://cloud.google.com/storage/docs/bucket-naming#requirements)).
  string bucket = 1;

  // Google Cloud Storage object containing the source.
  string object = 2;

  // Google Cloud Storage generation for the object. If the generation is
  // omitted, the latest generation will be used.
  int64 generation = 3;
}

// Location of the source in a Google Cloud Source Repository.
message RepoSource {
  // ID of the project that owns the Cloud Source Repository.
  string project_id = 1;

  // Name of the Cloud Source Repository.
  string repo_name = 2;

  // A revision within the Cloud Source Repository must be specified in
  // one of these ways.
  oneof revision {
    // Regex matching branches to build.
    //
    // The syntax of the regular expressions accepted is the syntax accepted by
    // RE2 and described at https://github.com/google/re2/wiki/Syntax
    string branch_name = 3;

    // Regex matching tags to build.
    //
    // The syntax of the regular expressions accepted is the syntax accepted by
    // RE2 and described at https://github.com/google/re2/wiki/Syntax
    string tag_name = 4;

    // Explicit commit SHA to build.
    string commit_sha = 5;
  }

  // Directory, relative to the source root, in which to run the build.
  //
  // This must be a relative path. If a step's `dir` is specified and is an
  // absolute path, this value is ignored for that step's execution.
  string dir = 7;

  // Only trigger a build if the revision regex does NOT match the revision
  // regex.
  bool invert_regex = 8;

  // Substitutions to use in a triggered build.
  // Should only be used with RunBuildTrigger
  map<string, string> substitutions = 9;
}

// A step in the build pipeline.
message BuildStep {
  // The name of the container image that will run this particular
  // build step.
  //
  // If the image is available in the host's Docker daemon's cache, it
  // will be run directly. If not, the host will attempt to pull the image
  // first, using the builder service account's credentials if necessary.
  //
  // The Docker daemon's cache will already have the latest versions of all of
  // the officially supported build steps
  // ([https://github.com/GoogleCloudPlatform/cloud-builders](https://github.com/GoogleCloudPlatform/cloud-builders)).
  // The Docker daemon will also have cached many of the layers for some popular
  // images, like "ubuntu", "debian", but they will be refreshed at the time you
  // attempt to use them.
  //
  // If you built an image in a previous build step, it will be stored in the
  // host's Docker daemon's cache and is available to use as the name for a
  // later build step.
  string name = 1;

  // A list of environment variable definitions to be used when running a step.
  //
  // The elements are of the form "KEY=VALUE" for the environment variable "KEY"
  // being given the value "VALUE".
  repeated string env = 2;

  // A list of arguments that will be presented to the step when it is started.
  //
  // If the image used to run the step's container has an entrypoint, the `args`
  // are used as arguments to that entrypoint. If the image does not define
  // an entrypoint, the first element in args is used as the entrypoint,
  // and the remainder will be used as arguments.
  repeated string args = 3;

  // Working directory to use when running this step's container.
  //
  // If this value is a relative path, it is relative to the build's working
  // directory. If this value is absolute, it may be outside the build's working
  // directory, in which case the contents of the path may not be persisted
  // across build step executions, unless a `volume` for that path is specified.
  //
  // If the build specifies a `RepoSource` with `dir` and a step with a `dir`,
  // which specifies an absolute path, the `RepoSource` `dir` is ignored for
  // the step's execution.
  string dir = 4;

  // Unique identifier for this build step, used in `wait_for` to
  // reference this build step as a dependency.
  string id = 5;

  // The ID(s) of the step(s) that this build step depends on.
  // This build step will not start until all the build steps in `wait_for`
  // have completed successfully. If `wait_for` is empty, this build step will
  // start when all previous build steps in the `Build.Steps` list have
  // completed successfully.
  repeated string wait_for = 6;

  // Entrypoint to be used instead of the build step image's default entrypoint.
  // If unset, the image's default entrypoint is used.
  string entrypoint = 7;

  // A list of environment variables which are encrypted using a Cloud Key
  // Management Service crypto key. These values must be specified in the
  // build's `Secret`.
  repeated string secret_env = 8;

  // List of volumes to mount into the build step.
  //
  // Each volume is created as an empty volume prior to execution of the
  // build step. Upon completion of the build, volumes and their contents are
  // discarded.
  //
  // Using a named volume in only one step is not valid as it is indicative
  // of a build request with an incorrect configuration.
  repeated Volume volumes = 9;

  // Stores timing information for executing this build step.
  TimeSpan timing = 10;

  // Stores timing information for pulling this build step's
  // builder image only.
  TimeSpan pull_timing = 13;

  // Time limit for executing this build step. If not defined, the step has no
  // time limit and will be allowed to continue to run until either it completes
  // or the build itself times out.
  google.protobuf.Duration timeout = 11;

  // Status of the build step. At this time, build step status is
  // only updated on build completion; step status is not updated in real-time
  // as the build progresses.
  BuildEventData.Status status = 12;
}

// Volume describes a Docker container volume which is mounted into build steps
// in order to persist files across build step execution.
message Volume {
  // Name of the volume to mount.
  //
  // Volume names must be unique per build step and must be valid names for
  // Docker volumes. Each named volume must be used by at least two build steps.
  string name = 1;

  // Path at which to mount the volume.
  //
  // Paths must be absolute and cannot conflict with other volume paths on the
  // same build step or with certain reserved volume paths.
  string path = 2;
}

// Artifacts created by the build pipeline.
message Results {
  // Container images that were built as a part of the build.
  repeated BuiltImage images = 2;

  // List of build step digests, in the order corresponding to build step
  // indices.
  repeated string build_step_images = 3;

  // Path to the artifact manifest. Only populated when artifacts are uploaded.
  string artifact_manifest = 4;

  // Number of artifacts uploaded. Only populated when artifacts are uploaded.
  int64 num_artifacts = 5;

  // List of build step outputs, produced by builder images, in the order
  // corresponding to build step indices.
  //
  // [Cloud Builders](https://cloud.google.com/cloud-build/docs/cloud-builders)
  // can produce this output by writing to `$BUILDER_OUTPUT/output`.
  // Only the first 4KB of data is stored.
  repeated bytes build_step_outputs = 6;

  // Time to push all non-container artifacts.
  TimeSpan artifact_timing = 7;
}

// An image built by the pipeline.
message BuiltImage {
  // Name used to push the container image to Google Container Registry, as
  // presented to `docker push`.
  string name = 1;

  // Docker Registry 2.0 digest.
  string digest = 3;

  // Stores timing information for pushing the specified image.
  TimeSpan push_timing = 4;
}

// Artifacts produced by a build that should be uploaded upon
// successful completion of all build steps.
message Artifacts {
  // Files in the workspace to upload to Cloud Storage upon successful
  // completion of all build steps.
  message ArtifactObjects {
    // Cloud Storage bucket and optional object path, in the form
    // "gs://bucket/path/to/somewhere/". (see [Bucket Name
    // Requirements](https://cloud.google.com/storage/docs/bucket-naming#requirements)).
    //
    // Files in the workspace matching any path pattern will be uploaded to
    // Cloud Storage with this location as a prefix.
    string location = 1;

    // Path globs used to match files in the build's workspace.
    repeated string paths = 2;

    // Stores timing information for pushing all artifact objects.
    TimeSpan timing = 3;
  }

  // A list of images to be pushed upon the successful completion of all build
  // steps.
  //
  // The images will be pushed using the builder service account's credentials.
  //
  // The digests of the pushed images will be stored in the Build resource's
  // results field.
  //
  // If any of the images fail to be pushed, the build is marked FAILURE.
  repeated string images = 1;

  // A list of objects to be uploaded to Cloud Storage upon successful
  // completion of all build steps.
  //
  // Files in the workspace matching specified paths globs will be uploaded to
  // the specified Cloud Storage location using the builder service account's
  // credentials.
  //
  // The location and generation of the uploaded objects will be stored in the
  // Build resource's results field.
  //
  // If any objects fail to be pushed, the build is marked FAILURE.
  ArtifactObjects objects = 2;
}

// Start and end times for a build execution phase.
message TimeSpan {
  // Start of time span.
  google.protobuf.Timestamp start_time = 1;

  // End of time span.
  google.protobuf.Timestamp end_time = 2;
}

// Provenance of the source. Ways to find the original source, or verify that
// some source was used for this build.
message SourceProvenance {
  // A copy of the build's `source.storage_source`, if exists, with any
  // generations resolved.
  StorageSource resolved_storage_source = 3;

  // A copy of the build's `source.repo_source`, if exists, with any
  // revisions resolved.
  RepoSource resolved_repo_source = 6;

  // Hash(es) of the build source, which can be used to verify that
  // the original source integrity was maintained in the build. Note that
  // `FileHashes` will only be populated if `BuildOptions` has requested a
  // `SourceProvenanceHash`.
  //
  // The keys to this map are file paths used as build source and the values
  // contain the hash values for those files.
  //
  // If the build source came in a single package such as a gzipped tarfile
  // (`.tar.gz`), the `FileHash` will be for the single path to that file.
  map<string, FileHashes> file_hashes = 4;
}

// Container message for hashes of byte content of files, used in
// SourceProvenance messages to verify integrity of source input to the build.
message FileHashes {
  // Collection of file hashes.
  repeated Hash file_hash = 1;
}

// Container message for hash values.
message Hash {
  // Specifies the hash algorithm, if any.
  enum HashType {
    // No hash requested.
    NONE = 0;

    // Use a sha256 hash.
    SHA256 = 1;

    // Use a md5 hash.
    MD5 = 2;
  }

  // The type of hash that was performed.
  HashType type = 1;

  // The hash value.
  bytes value = 2;
}

// Pairs a set of secret environment variables containing encrypted
// values with the Cloud KMS key to use to decrypt the value.
message Secret {
  // Cloud KMS key name to use to decrypt these envs.
  string kms_key_name = 1;

  // Map of environment variable name to its encrypted value.
  //
  // Secret environment variables must be unique across all of a build's
  // secrets, and must be used by at least one build step. Values can be at most
  // 64 KB in size. There can be at most 100 secret values across all of a
  // build's secrets.
  map<string, bytes> secret_env = 3;
}

// Optional arguments to enable specific features of builds.
message BuildOptions {
  // Specifies the manner in which the build should be verified, if at all.
  enum VerifyOption {
    // Not a verifiable build. (default)
    NOT_VERIFIED = 0;

    // Verified build.
    VERIFIED = 1;
  }

  // Supported VM sizes.
  enum MachineType {
    // Standard machine type.
    UNSPECIFIED = 0;

    // Highcpu machine with 8 CPUs.
    N1_HIGHCPU_8 = 1;

    // Highcpu machine with 32 CPUs.
    N1_HIGHCPU_32 = 2;
  }

  // Specifies the behavior when there is an error in the substitution checks.
  enum SubstitutionOption {
    // Fails the build if error in substitutions checks, like missing
    // a substitution in the template or in the map.
    MUST_MATCH = 0;

    // Do not fail the build if error in substitutions checks.
    ALLOW_LOOSE = 1;
  }

  // Specifies the behavior when writing build logs to Google Cloud Storage.
  enum LogStreamingOption {
    // Service may automatically determine build log streaming behavior.
    STREAM_DEFAULT = 0;

    // Build logs should be streamed to Google Cloud Storage.
    STREAM_ON = 1;

    // Build logs should not be streamed to Google Cloud Storage; they will be
    // written when the build is completed.
    STREAM_OFF = 2;
  }

  // Specifies the logging mode.
  enum LoggingMode {
    // The service determines the logging mode. The default is `LEGACY`. Do not
    // rely on the default logging behavior as it may change in the future.
    LOGGING_UNSPECIFIED = 0;

    // Stackdriver logging and Cloud Storage logging are enabled.
    LEGACY = 1;

    // Only Cloud Storage logging is enabled.
    GCS_ONLY = 2;
  }

  // Requested hash for SourceProvenance.
  repeated Hash.HashType source_provenance_hash = 1;

  // Requested verifiability options.
  VerifyOption requested_verify_option = 2;

  // Compute Engine machine type on which to run the build.
  MachineType machine_type = 3;

  // Requested disk size for the VM that runs the build. Note that this is *NOT*
  // "disk free"; some of the space will be used by the operating system and
  // build utilities. Also note that this is the minimum disk size that will be
  // allocated for the build -- the build may run with a larger disk than
  // requested. At present, the maximum disk size is 1000GB; builds that request
  // more than the maximum are rejected with an error.
  int64 disk_size_gb = 6;

  // Option to specify behavior when there is an error in the substitution
  // checks.
  SubstitutionOption substitution_option = 4;

  // Option to define build log streaming behavior to Google Cloud
  // Storage.
  LogStreamingOption log_streaming_option = 5;

  // Option to specify a `WorkerPool` for the build.
  // Format: projects/{project}/locations/{location}/workerPools/{workerPool}
  string worker_pool = 7;

  // Option to specify the logging mode, which determines where the logs are
  // stored.
  LoggingMode logging = 11;

  // A list of global environment variable definitions that will exist for all
  // build steps in this build. If a variable is defined in both globally and in
  // a build step, the variable will use the build step value.
  //
  // The elements are of the form "KEY=VALUE" for the environment variable "KEY"
  // being given the value "VALUE".
  repeated string env = 12;

  // A list of global environment variables, which are encrypted using a Cloud
  // Key Management Service crypto key. These values must be specified in the
  // build's `Secret`. These variables will be available to all build steps
  // in this build.
  repeated string secret_env = 13;

  // Global list of volumes to mount for ALL build steps
  //
  // Each volume is created as an empty volume prior to starting the build
  // process. Upon completion of the build, volumes and their contents are
  // discarded. Global volume names and paths cannot conflict with the volumes
  // defined a build step.
  //
  // Using a global volume in a build with only one step is not valid as
  // it is indicative of a build request with an incorrect configuration.
  repeated Volume volumes = 14;
}