| // Copyright 2016 Google Inc. | |
| // | |
| // 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.devtools.cloudbuild.v1; | |
| import "google/api/annotations.proto"; | |
| import "google/longrunning/operations.proto"; | |
| import "google/protobuf/duration.proto"; | |
| import "google/protobuf/empty.proto"; | |
| import "google/protobuf/timestamp.proto"; | |
| option go_package = "google.golang.org/genproto/googleapis/devtools/cloudbuild/v1;cloudbuild"; | |
| option java_multiple_files = true; | |
| option java_package = "com.google.cloudbuild.v1"; | |
| option objc_class_prefix = "GCB"; | |
| // Manages container image build requests in the cloud. | |
| // | |
| // The main concept used by this API is a Build, which describes the location of | |
| // the source to build, how to build the source into a container image, and what | |
| // tag to apply to the built image when it is pushed to Google Container | |
| // Registry. | |
| // | |
| // A user can list previously-requested builds or get builds by their ID to | |
| // determine the status of the build. | |
| service CloudBuild { | |
| // Starts a build with the specified configuration. | |
| // | |
| // The long-running Operation returned by this method will include the ID of | |
| // the build, which can be passed to GetBuild to determine its status (e.g., | |
| // success or failure). | |
| rpc CreateBuild(CreateBuildRequest) returns (google.longrunning.Operation) { | |
| option (google.api.http) = { post: "/v1/projects/{project_id}/builds" body: "build" }; | |
| } | |
| // Returns information about a previously requested build. | |
| // | |
| // The Build that is returned includes its status (e.g., success or failure, | |
| // or in-progress), and timing information. | |
| rpc GetBuild(GetBuildRequest) returns (Build) { | |
| option (google.api.http) = { get: "/v1/projects/{project_id}/builds/{id}" }; | |
| } | |
| // Lists previously requested builds. | |
| // | |
| // Previously requested builds may still be in-progress, or may have finished | |
| // successfully or unsuccessfully. | |
| rpc ListBuilds(ListBuildsRequest) returns (ListBuildsResponse) { | |
| option (google.api.http) = { get: "/v1/projects/{project_id}/builds" }; | |
| } | |
| // Cancels a requested build in progress. | |
| rpc CancelBuild(CancelBuildRequest) returns (Build) { | |
| option (google.api.http) = { post: "/v1/projects/{project_id}/builds/{id}:cancel" body: "*" }; | |
| } | |
| // Creates a new BuildTrigger. | |
| // | |
| // This API is experimental. | |
| rpc CreateBuildTrigger(CreateBuildTriggerRequest) returns (BuildTrigger) { | |
| option (google.api.http) = { post: "/v1/projects/{project_id}/triggers" body: "trigger" }; | |
| } | |
| // Gets information about a BuildTrigger. | |
| // | |
| // This API is experimental. | |
| rpc GetBuildTrigger(GetBuildTriggerRequest) returns (BuildTrigger) { | |
| option (google.api.http) = { get: "/v1/projects/{project_id}/triggers/{trigger_id}" }; | |
| } | |
| // Lists existing BuildTrigger. | |
| // | |
| // This API is experimental. | |
| rpc ListBuildTriggers(ListBuildTriggersRequest) returns (ListBuildTriggersResponse) { | |
| option (google.api.http) = { get: "/v1/projects/{project_id}/triggers" }; | |
| } | |
| // Deletes an BuildTrigger by its project ID and trigger ID. | |
| // | |
| // This API is experimental. | |
| rpc DeleteBuildTrigger(DeleteBuildTriggerRequest) returns (google.protobuf.Empty) { | |
| option (google.api.http) = { delete: "/v1/projects/{project_id}/triggers/{trigger_id}" }; | |
| } | |
| // Updates an BuildTrigger by its project ID and trigger ID. | |
| // | |
| // This API is experimental. | |
| rpc UpdateBuildTrigger(UpdateBuildTriggerRequest) returns (BuildTrigger) { | |
| option (google.api.http) = { patch: "/v1/projects/{project_id}/triggers/{trigger_id}" body: "trigger" }; | |
| } | |
| } | |
| // StorageSource describes the location of the source in an archive file in | |
| // Google Cloud Storage. | |
| message StorageSource { | |
| // Google Cloud Storage bucket containing source (see | |
| // [Bucket Name | |
| // Requirements](https://cloud.google.com/storage/docs/bucket-naming#requirements)). | |
| string bucket = 1; | |
| // Google Cloud Storage object containing source. | |
| // | |
| // This object must be a gzipped archive file (.tar.gz) containing source to | |
| // build. | |
| string object = 2; | |
| // Google Cloud Storage generation for the object. If the generation is | |
| // omitted, the latest generation will be used. | |
| int64 generation = 3; | |
| } | |
| // RepoSource describes the location of the source in a Google Cloud Source | |
| // Repository. | |
| message RepoSource { | |
| // ID of the project that owns the repo. If omitted, the project ID requesting | |
| // the build is assumed. | |
| string project_id = 1; | |
| // Name of the repo. If omitted, the name "default" is assumed. | |
| string repo_name = 2; | |
| // A revision within the source repository must be specified in | |
| // one of these ways. | |
| oneof revision { | |
| // Name of the branch to build. | |
| string branch_name = 3; | |
| // Name of the tag to build. | |
| string tag_name = 4; | |
| // Explicit commit SHA to build. | |
| string commit_sha = 5; | |
| } | |
| } | |
| // Source describes the location of the source in a supported storage | |
| // service. | |
| message Source { | |
| // Describes location of source. | |
| oneof source { | |
| // If provided, get the source from this location in in Google Cloud | |
| // Storage. | |
| StorageSource storage_source = 2; | |
| // If provided, get source from this location in a Cloud Repo. | |
| RepoSource repo_source = 3; | |
| } | |
| } | |
| // BuiltImage describes 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; | |
| } | |
| // BuildStep describes a step to perform in the build pipeline. | |
| message BuildStep { | |
| // The name of the container image that will run this particular build step. | |
| // | |
| // If the image is already 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). 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, these args | |
| // will be used as arguments to that entrypoint. If the image does not define | |
| // an entrypoint, the first element in args will be used as the entrypoint, | |
| // and the remainder will be used as arguments. | |
| repeated string args = 3; | |
| // Working directory (relative to project source root) to use when running | |
| // this operation's container. | |
| string dir = 4; | |
| // Optional 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; | |
| // Optional entrypoint to be used instead of the build step image's default | |
| // If unset, the image's default will be used. | |
| string entrypoint = 7; | |
| } | |
| // Results describes the artifacts created by the build pipeline. | |
| message Results { | |
| // Images that were built as a part of the build. | |
| repeated BuiltImage images = 2; | |
| // List of build step digests, in order corresponding to build step indices. | |
| repeated string build_step_images = 3; | |
| } | |
| // A build resource in the Container Builder API. | |
| // | |
| // At a high level, a Build describes where to find source code, how to build | |
| // it (for example, the builder image to run on the source), and what tag to | |
| // apply to the built image when it is pushed to Google Container Registry. | |
| // | |
| // Fields can include the following variables which will be expanded when the | |
| // build is created: | |
| // | |
| // - $PROJECT_ID: the project ID of the build. | |
| // - $BUILD_ID: the autogenerated ID of the build. | |
| // - $REPO_NAME: the source repository name specified by RepoSource. | |
| // - $BRANCH_NAME: the branch name specified by RepoSource. | |
| // - $TAG_NAME: the tag name specified by RepoSource. | |
| // - $REVISION_ID or $COMMIT_SHA: the commit SHA specified by RepoSource or | |
| // resolved from the specified branch or tag. | |
| message Build { | |
| // Possible status of a build. | |
| enum Status { | |
| // Status of the build is unknown. | |
| STATUS_UNKNOWN = 0; | |
| // Build is queued; work has not yet begun. | |
| QUEUED = 1; | |
| // Build is being executed. | |
| WORKING = 2; | |
| // Build finished successfully. | |
| SUCCESS = 3; | |
| // Build failed to complete successfully. | |
| FAILURE = 4; | |
| // Build failed due to an internal cause. | |
| INTERNAL_ERROR = 5; | |
| // Build took longer than was allowed. | |
| TIMEOUT = 6; | |
| // Build was canceled by a user. | |
| CANCELLED = 7; | |
| } | |
| // Unique identifier of the build. | |
| // @OutputOnly | |
| string id = 1; | |
| // ID of the project. | |
| // @OutputOnly. | |
| string project_id = 16; | |
| // Status of the build. | |
| // @OutputOnly | |
| Status status = 2; | |
| // Customer-readable message about the current status. | |
| // @OutputOnly | |
| string status_detail = 24; | |
| // Describes where to find the source files to build. | |
| Source source = 3; | |
| // Describes the operations to be performed on the workspace. | |
| repeated BuildStep steps = 11; | |
| // Results of the build. | |
| // @OutputOnly | |
| Results results = 10; | |
| // Time at which the request to create the build was received. | |
| // @OutputOnly | |
| google.protobuf.Timestamp create_time = 6; | |
| // Time at which execution of the build was started. | |
| // @OutputOnly | |
| 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. | |
| // @OutputOnly | |
| 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. | |
| // | |
| // Default time is ten minutes. | |
| google.protobuf.Duration timeout = 12; | |
| // 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 = 13; | |
| // 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. | |
| // @OutputOnly | |
| SourceProvenance source_provenance = 21; | |
| // The ID of the BuildTrigger that triggered this build, if it was | |
| // triggered automatically. | |
| // @OutputOnly | |
| string build_trigger_id = 22; | |
| // Special options for this build. | |
| BuildOptions options = 23; | |
| // URL to logs for this build in Google Cloud Logging. | |
| // @OutputOnly | |
| string log_url = 25; | |
| // Substitutions data for Build resource. | |
| map<string, string> substitutions = 29; | |
| } | |
| // Metadata for build operations. | |
| message BuildOperationMetadata { | |
| // The build that the operation is tracking. | |
| Build build = 1; | |
| } | |
| // 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. | |
| // @OutputOnly | |
| 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; | |
| } | |
| // The type of hash that was performed. | |
| HashType type = 1; | |
| // The hash value. | |
| bytes value = 2; | |
| } | |
| // Request to create a new build. | |
| message CreateBuildRequest { | |
| // ID of the project. | |
| string project_id = 1; | |
| // Build resource to create. | |
| Build build = 2; | |
| } | |
| // Request to get a build. | |
| message GetBuildRequest { | |
| // ID of the project. | |
| string project_id = 1; | |
| // ID of the build. | |
| string id = 2; | |
| } | |
| // Request to list builds. | |
| message ListBuildsRequest { | |
| // ID of the project. | |
| string project_id = 1; | |
| // Number of results to return in the list. | |
| int32 page_size = 2; | |
| // Token to provide to skip to a particular spot in the list. | |
| string page_token = 3; | |
| // The raw filter text to constrain the results. | |
| string filter = 8; | |
| } | |
| // Response including listed builds. | |
| message ListBuildsResponse { | |
| // Builds will be sorted by create_time, descending. | |
| repeated Build builds = 1; | |
| // Token to receive the next page of results. | |
| string next_page_token = 2; | |
| } | |
| // Request to cancel an ongoing build. | |
| message CancelBuildRequest { | |
| // ID of the project. | |
| string project_id = 1; | |
| // ID of the build. | |
| string id = 2; | |
| } | |
| // Configuration for an automated build in response to source repository | |
| // changes. | |
| message BuildTrigger { | |
| // Unique identifier of the trigger. | |
| // | |
| // @OutputOnly | |
| string id = 1; | |
| // Human-readable description of this trigger. | |
| string description = 10; | |
| // Template describing the types of source changes to trigger a build. | |
| // | |
| // Branch and tag names in trigger templates are interpreted as regular | |
| // expressions. Any branch or tag change that matches that regular expression | |
| // will trigger a build. | |
| RepoSource trigger_template = 7; | |
| // Template describing the Build request to make when the trigger is matched. | |
| oneof build_template { | |
| // Contents of the build template. | |
| Build build = 4; | |
| // Path, from the source root, to a file whose contents is used for the | |
| // template. | |
| string filename = 8; | |
| } | |
| // Time when the trigger was created. | |
| // | |
| // @OutputOnly | |
| google.protobuf.Timestamp create_time = 5; | |
| // If true, the trigger will never result in a build. | |
| bool disabled = 9; | |
| // Substitutions data for Build resource. | |
| map<string, string> substitutions = 11; | |
| } | |
| // Request to create a new BuildTrigger. | |
| message CreateBuildTriggerRequest { | |
| // ID of the project for which to configure automatic builds. | |
| string project_id = 1; | |
| // BuildTrigger to create. | |
| BuildTrigger trigger = 2; | |
| } | |
| // Returns the BuildTrigger with the specified ID. | |
| message GetBuildTriggerRequest { | |
| // ID of the project that owns the trigger. | |
| string project_id = 1; | |
| // ID of the BuildTrigger to get. | |
| string trigger_id = 2; | |
| } | |
| // Request to list existing BuildTriggers. | |
| message ListBuildTriggersRequest { | |
| // ID of the project for which to list BuildTriggers. | |
| string project_id = 1; | |
| } | |
| // Response containing existing BuildTriggers. | |
| message ListBuildTriggersResponse { | |
| // BuildTriggers for the project, sorted by create_time descending. | |
| repeated BuildTrigger triggers = 1; | |
| } | |
| // Request to delete a BuildTrigger. | |
| message DeleteBuildTriggerRequest { | |
| // ID of the project that owns the trigger. | |
| string project_id = 1; | |
| // ID of the BuildTrigger to delete. | |
| string trigger_id = 2; | |
| } | |
| // Request to update an existing BuildTrigger. | |
| message UpdateBuildTriggerRequest { | |
| // ID of the project that owns the trigger. | |
| string project_id = 1; | |
| // ID of the BuildTrigger to update. | |
| string trigger_id = 2; | |
| // BuildTrigger to update. | |
| BuildTrigger trigger = 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; | |
| } | |
| // Requested hash for SourceProvenance. | |
| repeated Hash.HashType source_provenance_hash = 1; | |
| // Requested verifiability options. | |
| VerifyOption requested_verify_option = 2; | |
| } |