Integrating Cloud Deploy with other systems

You can integrate Cloud Deploy with some of the other systems you rely on for software delivery. This page describes how to integrate Cloud Deploy with the following:

Test tooling
Workflow management

See Integrating with your CI system to learn how to call Cloud Deploy from your CI pipeline.

Before you begin

The instructions on this page assume you already meet the following conditions:

You have enabled the applicable APIs
You have at least one delivery pipeline defined and registered with Cloud Deploy.
You have at least one target defined, and your delivery pipeline references that target.
You have set up Pub/Sub notifications to receive notifications from the following topics:
- clouddeploy-operations
- clouddeploy-approvals

Integrating with automated testing

You can use Cloud Deploy with Pub/Sub to integrate testing with your delivery pipeline, so you can promote the release automatically, for continuous delivery.

You can also use annotations on a rollout to provide a link to test results. For more information, see Using labels and annotations with Cloud Deploy.

Using Pub/Sub to automate promotion

Listen to Pub/Sub messages from the clouddeploy-operations topic.

The message contains the following attributes:
- Action: SUCCEED
- ResourceType: Rollout
- Resource: projects/.../locations/.../deliveryPipelines/.../releases/.../rollouts/...
When you receive a notification that deployment has succeeded, run your tests on your deployed application.
When your tests succeed, call Cloud Deploy to automatically promote to the next stage:
```
gcloud deploy releases promote RELEASE_NAME \
--delivery-pipeline=PIPELINE_NAME \
--region=REGION \
--annotations=KEY=VALUE,...
```
where:
- RELEASE_NAME
  
  is the name of the release. This value is required.
- PIPELINE_NAME
  
  is the name of the delivery pipeline managing this release. This value is required.
- REGION
  
  is the region in which the pipeline is running. If you've set the property deploy/region, you can omit this flag.
- KEY=VALUE,...
  
  is a list of one or more key-value string pairs, comma-separated, which can contain information about your test results and other testing information. Here's an example:
  
  gcloud deploy releases promote --annotations="from_target=test,status=stable"
  
  Annotations on the rollout are immutable, so if you add a status annotation, you can't later update that status on the same rollout.

Using annotations to provide access to test results

If you have the URL pointing to where test results can be accessed, you can provide that URL as an annotation on a rollout, using the --annotations flag. Here's an example:

gcloud deploy releases promote --delivery-pipeline=my-demo-app-1 --region=us-central1 --project=my-demo-app-1-project --release=test-release-001 --annotations="test_results_url=https://example.com/results/my-demo-app-test-results-dev"

For more information, see Using labels and annotations with Cloud Deploy.

Integrating with third-party workflow management

Cloud Deploy publishes operational messages to Pub/Sub. Your workflow management tool can subscribe to these Pub/Sub topics and use them to trigger specific workflows.

For approvals

The clouddeploy-approvals topic notifies your system when an approval is required for a rollout. Your external workflow system can then work its magic to get the approval, then call gcloud deploy rollouts approve.

The account that issues the rollouts approve command must have the predefined IAM role roles/clouddeploy.approver.

To set up an external approval workflow:

Require approval on the target.

In the definition for that target, include requireApproval: true.
To consume the messages, subscribe to the clouddeploy-approvals Pub/Sub topic, and set up your workflow management system.
When your workflow management system receives a message from the clouddeploy-approvals topic that includes "Action": "Required", it kicks off an approval workflow, configured according to the requirements of your organization.

The message also includes a reference to the rollout to be approved, in the following format:

Resource: projects/.../locations/.../deliveryPipelines/.../releases/.../rollouts/...

The output of the approval workflow is an approval or rejection of the rollout.
Your workflow management system returns the approval or rejection to Cloud Deploy in the form of the following command:

The command for approval is as follows:
```
gcloud deploy rollouts approve ROLLOUT \
--delivery-pipeline=PIPELINE_NAME \
--region=REGION \
--release=RELEASE_NAME
```
The command for rejecting the rollout is as follows:
```
gcloud deploy rollouts reject ROLLOUT \
--delivery-pipeline=PIPELINE_NAME \
--region=REGION \
--release=RELEASE_NAME
```
where:
- ROLLOUT
  
  is the name of the rollout for which approval was requested.
- PIPELINE_NAME
  
  is the delivery pipeline managing deployment of your application.
- RELEASE_NAME
  
  is the name of the release with which this rollout is associated.
- REGION
  
  is the region in which the delivery pipeline is running.

Here's an example:

gcloud deploy rollouts approve test-rollout --delivery-pipeline=web-app --release=test-release --region=us-central1