feat: Add SecretManager-related resources and messages for correspo…

…nding integration. (#73)

fix: Specify `build` as the body of a `CreateBuild` call. The Cloud Build API has always assumed this, but now we are actually specifying it.

feat: Add `ReceiveTriggerWebhook` for webhooks activating specific triggers.

docs: Update field docs on required-ness behavior and fix typos.

docs: Add `$PROJECT_NUMBER` as a substitution variable.

docs: Clarify lifetime/expiration behavior around `ListBuilds` page tokens.

feat: Add `COMMENTS_ENABLED_FOR_EXTERNAL_CONTRIBUTORS_ONLY` for corresponding comment control behavior with triggered builds.

feat: Add `E2_HIGHCPU_8` and `E2_HIGHCPU_32` machine types.

.pre-commit-config.yaml

@@ -12,6 +12,6 @@ repos:
     hooks:
     - id: black
 -   repo: https://gitlab.com/pycqa/flake8
-    rev: 3.8.4
+    rev: 3.9.0
     hooks:
     - id: flake8

UPGRADING.md

@@ -17,10 +17,10 @@ The 2.0.0 release requires Python 3.6+.
 
 Methods expect request objects. We provide a script that will convert most common use cases.
 
-* Install the library
+* Install the library with `libcst`.
 
 ```py
-python3 -m pip install google-cloud-build
+python3 -m pip install google-cloud-build[libcst]
 ```
 
 * The script `fixup_cloudbuild_v1_keywords.py` is shipped with the library. It expects

google/cloud/devtools/cloudbuild/__init__.py

@@ -45,6 +45,7 @@
 from google.cloud.devtools.cloudbuild_v1.types.cloudbuild import GetWorkerPoolRequest
 from google.cloud.devtools.cloudbuild_v1.types.cloudbuild import GitHubEventsConfig
 from google.cloud.devtools.cloudbuild_v1.types.cloudbuild import Hash
+from google.cloud.devtools.cloudbuild_v1.types.cloudbuild import InlineSecret
 from google.cloud.devtools.cloudbuild_v1.types.cloudbuild import (
     ListBuildTriggersRequest,
 )
@@ -58,11 +59,19 @@
 from google.cloud.devtools.cloudbuild_v1.types.cloudbuild import Network
 from google.cloud.devtools.cloudbuild_v1.types.cloudbuild import PullRequestFilter
 from google.cloud.devtools.cloudbuild_v1.types.cloudbuild import PushFilter
+from google.cloud.devtools.cloudbuild_v1.types.cloudbuild import (
+    ReceiveTriggerWebhookRequest,
+)
+from google.cloud.devtools.cloudbuild_v1.types.cloudbuild import (
+    ReceiveTriggerWebhookResponse,
+)
 from google.cloud.devtools.cloudbuild_v1.types.cloudbuild import RepoSource
 from google.cloud.devtools.cloudbuild_v1.types.cloudbuild import Results
 from google.cloud.devtools.cloudbuild_v1.types.cloudbuild import RetryBuildRequest
 from google.cloud.devtools.cloudbuild_v1.types.cloudbuild import RunBuildTriggerRequest
 from google.cloud.devtools.cloudbuild_v1.types.cloudbuild import Secret
+from google.cloud.devtools.cloudbuild_v1.types.cloudbuild import SecretManagerSecret
+from google.cloud.devtools.cloudbuild_v1.types.cloudbuild import Secrets
 from google.cloud.devtools.cloudbuild_v1.types.cloudbuild import Source
 from google.cloud.devtools.cloudbuild_v1.types.cloudbuild import SourceProvenance
 from google.cloud.devtools.cloudbuild_v1.types.cloudbuild import StorageSource
@@ -98,6 +107,7 @@
     "GetWorkerPoolRequest",
     "GitHubEventsConfig",
     "Hash",
+    "InlineSecret",
     "ListBuildTriggersRequest",
     "ListBuildTriggersResponse",
     "ListBuildsRequest",
@@ -107,11 +117,15 @@
     "Network",
     "PullRequestFilter",
     "PushFilter",
+    "ReceiveTriggerWebhookRequest",
+    "ReceiveTriggerWebhookResponse",
     "RepoSource",
     "Results",
     "RetryBuildRequest",
     "RunBuildTriggerRequest",
     "Secret",
+    "SecretManagerSecret",
+    "Secrets",
     "Source",
     "SourceProvenance",
     "StorageSource",

google/cloud/devtools/cloudbuild_v1/__init__.py

@@ -36,6 +36,7 @@
 from .types.cloudbuild import GetWorkerPoolRequest
 from .types.cloudbuild import GitHubEventsConfig
 from .types.cloudbuild import Hash
+from .types.cloudbuild import InlineSecret
 from .types.cloudbuild import ListBuildTriggersRequest
 from .types.cloudbuild import ListBuildTriggersResponse
 from .types.cloudbuild import ListBuildsRequest
@@ -45,11 +46,15 @@
 from .types.cloudbuild import Network
 from .types.cloudbuild import PullRequestFilter
 from .types.cloudbuild import PushFilter
+from .types.cloudbuild import ReceiveTriggerWebhookRequest
+from .types.cloudbuild import ReceiveTriggerWebhookResponse
 from .types.cloudbuild import RepoSource
 from .types.cloudbuild import Results
 from .types.cloudbuild import RetryBuildRequest
 from .types.cloudbuild import RunBuildTriggerRequest
 from .types.cloudbuild import Secret
+from .types.cloudbuild import SecretManagerSecret
+from .types.cloudbuild import Secrets
 from .types.cloudbuild import Source
 from .types.cloudbuild import SourceProvenance
 from .types.cloudbuild import StorageSource
@@ -82,6 +87,7 @@
     "GetWorkerPoolRequest",
     "GitHubEventsConfig",
     "Hash",
+    "InlineSecret",
     "ListBuildTriggersRequest",
     "ListBuildTriggersResponse",
     "ListBuildsRequest",
@@ -91,11 +97,15 @@
     "Network",
     "PullRequestFilter",
     "PushFilter",
+    "ReceiveTriggerWebhookRequest",
+    "ReceiveTriggerWebhookResponse",
     "RepoSource",
     "Results",
     "RetryBuildRequest",
     "RunBuildTriggerRequest",
     "Secret",
+    "SecretManagerSecret",
+    "Secrets",
     "Source",
     "SourceProvenance",
     "StorageSource",

google/cloud/devtools/cloudbuild_v1/proto/cloudbuild.proto

@@ -1,4 +1,4 @@
-// Copyright 2020 Google LLC
+// Copyright 2021 Google LLC
 //
 // Licensed under the Apache License, Version 2.0 (the "License");
 // you may not use this file except in compliance with the License.
@@ -19,6 +19,7 @@ package google.devtools.cloudbuild.v1;
 import "google/api/annotations.proto";
 import "google/api/client.proto";
 import "google/api/field_behavior.proto";
+import "google/api/httpbody.proto";
 import "google/api/resource.proto";
 import "google/longrunning/operations.proto";
 import "google/protobuf/duration.proto";
@@ -40,6 +41,18 @@ option (google.api.resource_definition) = {
   type: "iam.googleapis.com/ServiceAccount"
   pattern: "projects/{project}/serviceAccounts/{service_account}"
 };
+option (google.api.resource_definition) = {
+  type: "secretmanager.googleapis.com/Secret"
+  pattern: "projects/{project}/secrets/{secret}"
+};
+option (google.api.resource_definition) = {
+  type: "secretmanager.googleapis.com/SecretVersion"
+  pattern: "projects/{project}/secrets/{secret}/versions/{version}"
+};
+option (google.api.resource_definition) = {
+  type: "cloudkms.googleapis.com/CryptoKey"
+  pattern: "projects/{project}/locations/{location}/keyRings/{keyring}/cryptoKeys/{key}"
+};
 
 // Creates and manages builds on Google Cloud Platform.
 //
@@ -65,7 +78,7 @@ service CloudBuild {
       body: "build"
       additional_bindings {
         post: "/v1/{parent=projects/*/locations/*}/builds"
-        body: "*"
+        body: "build"
       }
     };
     option (google.api.method_signature) = "project_id,build";
@@ -223,6 +236,16 @@ service CloudBuild {
     };
   }
 
+  // ReceiveTriggerWebhook [Experimental] is called when the API receives a
+  // webhook request targeted at a specific trigger.
+  rpc ReceiveTriggerWebhook(ReceiveTriggerWebhookRequest)
+      returns (ReceiveTriggerWebhookResponse) {
+    option (google.api.http) = {
+      post: "/v1/projects/{project_id}/triggers/{trigger}:webhook"
+      body: "body"
+    };
+  }
+
   // Creates a `WorkerPool` to run the builds, and returns the new worker pool.
   //
   // This API is experimental.
@@ -274,8 +297,8 @@ message RunBuildTriggerRequest {
   // Required. ID of the trigger.
   string trigger_id = 2 [(google.api.field_behavior) = REQUIRED];
 
-  // Required. Source to build against this trigger.
-  RepoSource source = 3 [(google.api.field_behavior) = REQUIRED];
+  // Source to build against this trigger.
+  RepoSource source = 3;
 }
 
 // Location of the source in an archive file in Google Cloud Storage.
@@ -302,7 +325,7 @@ message RepoSource {
   // project ID requesting the build is assumed.
   string project_id = 1;
 
-  // Required. Name of the Cloud Source Repository.
+  // Name of the Cloud Source Repository.
   string repo_name = 2;
 
   // A revision within the Cloud Source Repository must be specified in
@@ -525,6 +548,7 @@ message ArtifactResult {
 // build is created:
 //
 // - $PROJECT_ID: the project ID of the build.
+// - $PROJECT_NUMBER: the project number 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.
@@ -669,6 +693,10 @@ message Build {
   repeated string tags = 31;
 
   // Secrets to decrypt using Cloud Key Management Service.
+  // Note: Secret Manager is the recommended technique
+  // for managing sensitive data with Cloud Build. Use `available_secrets` to
+  // configure builds to access secrets from Secret Manager. For instructions,
+  // see: https://cloud.google.com/cloud-build/docs/securing-builds/use-secrets
   repeated Secret secrets = 32;
 
   // Output only. Stores timing information for phases of the build. Valid keys
@@ -686,10 +714,13 @@ message Build {
   // Must be of the format `projects/{PROJECT_ID}/serviceAccounts/{ACCOUNT}`.
   // ACCOUNT can be email address or uniqueId of the service account.
   //
-  // This field is in alpha and is not publicly available.
+  // This field is in beta.
   string service_account = 42 [(google.api.resource_reference) = {
     type: "iam.googleapis.com/ServiceAccount"
   }];
+
+  // Secrets and secret environment variables.
+  Secrets available_secrets = 47;
 }
 
 // Artifacts produced by a build that should be uploaded upon
@@ -806,8 +837,53 @@ message Hash {
   bytes value = 2;
 }
 
+// Secrets and secret environment variables.
+message Secrets {
+  // Secrets in Secret Manager and associated secret environment variable.
+  repeated SecretManagerSecret secret_manager = 1;
+
+  // Secrets encrypted with KMS key and the associated secret environment
+  // variable.
+  repeated InlineSecret inline = 2;
+}
+
+// Pairs a set of secret environment variables mapped to encrypted
+// values with the Cloud KMS key to use to decrypt the value.
+message InlineSecret {
+  // Resource name of Cloud KMS crypto key to decrypt the encrypted value.
+  // In format: projects/*/locations/*/keyRings/*/cryptoKeys/*
+  string kms_key_name = 1 [(google.api.resource_reference) = {
+    type: "cloudkms.googleapis.com/CryptoKey"
+  }];
+
+  // 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> env_map = 2;
+}
+
+// Pairs a secret environment variable with a SecretVersion in Secret Manager.
+message SecretManagerSecret {
+  // Resource name of the SecretVersion. In format:
+  // projects/*/secrets/*/versions/*
+  string version_name = 1 [(google.api.resource_reference) = {
+    type: "secretmanager.googleapis.com/SecretVersion"
+  }];
+
+  // Environment variable name to associate with the secret.
+  // Secret environment variables must be unique across all of a build's
+  // secrets, and must be used by at least one build step.
+  string env = 2;
+}
+
 // Pairs a set of secret environment variables containing encrypted
 // values with the Cloud KMS key to use to decrypt the value.
+// Note: Use `kmsKeyName` with  `available_secrets` instead of using
+// `kmsKeyName` with `secret`. For instructions see:
+// https://cloud.google.com/cloud-build/docs/securing-builds/use-encrypted-credentials.
 message Secret {
   // Cloud KMS key name to use to decrypt these envs.
   string kms_key_name = 1;
@@ -865,7 +941,15 @@ message ListBuildsRequest {
   // Number of results to return in the list.
   int32 page_size = 2;
 
-  // Token to provide to skip to a particular spot in the list.
+  // The page token for the next page of Builds.
+  //
+  // If unspecified, the first page of results is returned.
+  //
+  // If the token is rejected for any reason, INVALID_ARGUMENT will be thrown.
+  // In this case, the token should be discarded, and pagination should be
+  // restarted from the first page of results.
+  //
+  // See https://google.aip.dev/158 for more.
   string page_token = 3;
 
   // The raw filter text to constrain the results.
@@ -878,12 +962,13 @@ message ListBuildsResponse {
   repeated Build builds = 1;
 
   // Token to receive the next page of results.
+  // This will be absent if the end of the response list has been reached.
   string next_page_token = 2;
 }
 
 // Request to cancel an ongoing build.
 message CancelBuildRequest {
-  // The name of the `Build` to retrieve.
+  // The name of the `Build` to cancel.
   // Format: `projects/{project}/locations/{location}/builds/{build}`
   string name = 4 [(google.api.resource_reference) = {
     type: "cloudbuild.googleapis.com/Build"
@@ -941,8 +1026,8 @@ message BuildTrigger {
     // Contents of the build template.
     Build build = 4;
 
-    // Path, from the source root, to a file whose contents is used for the
-    // template.
+    // Path, from the source root, to the build configuration file
+    // (i.e. cloudbuild.yaml).
     string filename = 8;
   }
 
@@ -1018,6 +1103,10 @@ message PullRequestFilter {
     // Enforce that repository owners or collaborators must comment on Pull
     // Requests before builds are triggered.
     COMMENTS_ENABLED = 1;
+
+    // Enforce that repository owners or collaborators must comment on external
+    // contributors' Pull Requests before builds are triggered.
+    COMMENTS_ENABLED_FOR_EXTERNAL_CONTRIBUTORS_ONLY = 2;
   }
 
   // Target refs to match.
@@ -1144,6 +1233,12 @@ message BuildOptions {
 
     // Highcpu machine with 32 CPUs.
     N1_HIGHCPU_32 = 2;
+
+    // Highcpu e2 machine with 8 CPUs.
+    E2_HIGHCPU_8 = 5;
+
+    // Highcpu e2 machine with 32 CPUs.
+    E2_HIGHCPU_32 = 6;
   }
 
   // Specifies the behavior when there is an error in the substitution checks.
@@ -1190,7 +1285,6 @@ message BuildOptions {
     CLOUD_LOGGING_ONLY = 5;
 
     // Turn off all logging. No build logs will be captured.
-    // Next ID: 6
     NONE = 4;
   }
 
@@ -1265,6 +1359,26 @@ message BuildOptions {
   repeated Volume volumes = 14;
 }
 
+// ReceiveTriggerWebhookRequest [Experimental] is the request object accepted by
+// the ReceiveTriggerWebhook method.
+message ReceiveTriggerWebhookRequest {
+  // HTTP request body.
+  google.api.HttpBody body = 1;
+
+  // Project in which the specified trigger lives
+  string project_id = 2;
+
+  // Name of the trigger to run the payload against
+  string trigger = 3;
+
+  // Secret token used for authorization if an OAuth token isn't provided.
+  string secret = 4;
+}
+
+// ReceiveTriggerWebhookResponse [Experimental] is the response object for the
+// ReceiveTriggerWebhook method.
+message ReceiveTriggerWebhookResponse {}
+
 // Configuration for a WorkerPool to run the builds.
 //
 // Workers are machines that Cloud Build uses to run your builds. By default,