canonical: https://jentic.com/apis/googleapis.com/clouddeploy

# Google Cloud Deploy API

Google Cloud Deploy is a managed, opinionated continuous-delivery service that promotes container images and Kubernetes manifests through a series of target environments such as staging and production. The API exposes delivery pipelines, releases, rollouts, targets, and approval steps so agents can promote a release to the next stage, abandon a release, approve a pending rollout, or roll back to a previous successful deployment. Cloud Deploy integrates with Cloud Build for build artefacts and with GKE, Cloud Run, and Anthos for deployment targets.

## For AI agents

Promote releases through staged delivery pipelines on GKE, Cloud Run, and Anthos, with approval gates, rollback, and rollout management. Useful for managed continuous-delivery workflows on GCP.

## Scope

Does not build artefacts, run application traffic, or store source code - use for staged release promotion, approval, and rollback only.

## Capabilities

- Create a delivery pipeline that defines the sequence of target environments
- Cut a release that promotes a specific container image through the pipeline
- Approve, advance, or abandon a pending rollout
- Roll back to a previous successful release on a given target
- Cancel a rollout that is mid-flight on a target environment
- List targets, releases, and rollouts to surface delivery state to dashboards
- Configure custom target types for delivery to non-default runtimes

## Use cases

### Staged Release Promotion to GKE

Platform teams use Cloud Deploy to promote a tested container image through dev, staging, and production GKE clusters with explicit approval gates between stages. Each promotion is an advanceRollout call; production rollouts wait on an approveRollout call from a release manager. Setup typically takes a day per service; subsequent releases take seconds.

Example prompt: Call POST /v1/{name}:advance on the rollout resource with phaseId set to the target phase, then POST /v1/{name}:approve once production is ready

### Automated Rollback on Failure

SRE workflows watch for elevated error rates after a rollout and call rollbackTarget to restore the previous release. The API returns a new rollout that re-applies the prior image and Kubernetes manifests, so service health returns to baseline without a manual rerun of the original pipeline.

Example prompt: Call POST /v1/{name}:rollbackTarget with the target resource name and an optional release reference to specify which release to roll back to

### Release Awaiting-Approval Dashboard

Release managers use the rollouts list endpoint with a filter on approvalState to surface every rollout currently waiting for sign-off. The dashboard pairs the data with deployment metadata so reviewers can approve or abandon with full context. The same endpoint backs alerting that escalates if a rollout stalls past a threshold.

Example prompt: Call GET on the rollouts collection with filter=approvalState=NEEDS_APPROVAL across the configured delivery pipelines

### AI Agent Release Approver via Jentic

An agent invoked by an on-call engineer searches Jentic for the right Cloud Deploy operation, gathers the rollout context, and either advances, approves, or rolls back the release based on the engineer's intent. Jentic injects a scoped OAuth token at execution time so the agent never holds long-lived credentials.

Example prompt: Search Jentic for 'approve google cloud deploy rollout', execute against POST /v1/{name}:approve with approved=true, and report the resulting rollout state

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| POST | /v1/{+name}:advance | Advance a rollout to its next phase |
| POST | /v1/{+name}:approve | Approve a rollout awaiting sign-off |
| POST | /v1/{+name}:abandon | Abandon a release that should no longer be promoted |
| POST | /v1/{+name}:cancel | Cancel an in-flight rollout |
| POST | /v1/{+name}:rollbackTarget | Roll back a target to a previous release |
| GET | /v1/{+name}/operations | List long-running operations on a resource |
| GET | /v1/{+name}/locations | List Cloud Deploy locations available to a project |

## Key resources

- **DeliveryPipelines** — Pipelines that define the sequence of target environments for promotion
- **Releases** — Versioned bundles of the artefact and manifests that flow through a pipeline
- **Rollouts** — Per-target executions that apply a release to a single environment
- **Targets** — Deployment targets such as GKE clusters, Cloud Run services, or custom runtimes

## Why Jentic

- **Setup:** Wiring the Cloud Deploy API by hand means setting up Google OAuth 2.0, minting short-lived tokens against the cloud-platform scope, and addressing each rollout by resource name against clouddeploy.googleapis.com yourself. Through Jentic you install once, import the Cloud Deploy API from the API Directory, store the OAuth credential once, and your agent calls it.
- **Permission scoping:** Cloud Deploy puts the rollout resource name in the URL path (/v1/{+name}:advance, /v1/{+name}:approve), so a rule can pin your agent to one delivery pipeline: it can advance and approve rollouts there and nothing else. You choose the operations it may call, so abandon, cancel, or rollbackTarget are not included unless you add them.
- **Credential handling:** Your Cloud Deploy OAuth credential is stored once, encrypted, by your own Jentic One instance and injected at execution time. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'approve a Cloud Deploy rollout' or 'roll back a deploy target', and Jentic returns the matching Cloud Deploy operation with its input schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **Cloud Build API** — Produces the container artefacts that Cloud Deploy promotes through environments
- **Kubernetes Engine API** — Manages the GKE clusters that serve as Cloud Deploy targets
- **Cloud Run Admin API** — Manages Cloud Run services that Cloud Deploy can target as a runtime

## FAQ

### What authentication does the Cloud Deploy API use?

The Cloud Deploy API uses OAuth 2.0 with the cloud-platform scope. Tokens are issued for a Google service account or end user. Through Jentic, the OAuth credential lives in your Jentic One instance and the agent receives a short-lived access token only - the underlying service account JSON never enters agent context.

### Can I promote a release to the next environment with this API?

Yes. Call POST /v1/{name}:advance on the rollout resource to move it to the next phase, or create a new rollout against the next target if the pipeline is configured for serial promotion. Production rollouts that require approval pause on a NEEDS_APPROVAL state until /v1/{name}:approve is called.

### What are the rate limits for the Cloud Deploy API?

Cloud Deploy quotas are published per-method in the Google Cloud console under the Cloud Deploy quota page; typical defaults are several hundred read requests per minute per project, with concurrent rollout limits per target type (GKE, Cloud Run, custom).

### How do I roll back a production release through Jentic?

Search Jentic for 'rollback google cloud deploy target' and execute against POST /v1/{name}:rollbackTarget on the target resource. The API creates a new rollout that re-applies the previous successful release; the agent can poll the rollout for completion and report the resulting state.

### Does Cloud Deploy support custom deployment targets?

Yes. Custom target types are first-class resources - define a customTargetType with a render and deploy action, and reference it from a target inside a delivery pipeline. The same approval, advance, abandon, and rollback verbs apply to custom targets.

### Is Cloud Deploy free?

Cloud Deploy charges a per-target-environment monthly fee documented on the Cloud Deploy pricing page. Builds run by Cloud Build and the runtime resources targeted (GKE, Cloud Run) are billed separately under their own services.

### Can I limit what my agent is allowed to do with the Cloud Deploy API?

Yes. Because you self-host Jentic One, your own rules decide which Cloud Deploy operations and credentials the agent may use. Since the rollout resource name sits in the URL path for calls like /v1/{name}:advance and /v1/{name}:approve, you can pin the agent to a single delivery pipeline and let it advance and approve rollouts there and nothing else. You choose the operations it may call, so abandon, cancel, and rollbackTarget stay off limits unless you add them, and the OAuth credential is injected at execution time rather than exposed to the agent.