This document describes the Cloud Deploy resources used to execute
[automations](https://docs.cloud.google.com/deploy/docs/automation).

You can configure Cloud Deploy to automatically perform certain delivery
pipeline tasks, such as promote a release or advance a rollout to a given phase.
These automations rely on two Cloud Deploy resources:

- The `Automation` itself

- The `AutomationRun`

These resources are described in this document.

## The `Automation` resource

An `Automation` is a Cloud Deploy resource that defines how to automate
one or more delivery pipeline tasks. The `Automation` associates one or more
target resources with one or more automation `rules`.

The `Automation` resource includes the following:

- A reference to the target (or targets) against which to perform the automation
  (the `selector`).

- An automation rule that determines how to do the automation.

- Metadata, such as `description`, `annotations`, and `labels`.

- A `suspended` property.

- The service account to use to perform the automation. The service account is
  required, and it must have the
  [necessary permissions](https://docs.cloud.google.com/deploy/docs/automation#roles_and_permissions_required)
  to perform the automation. Automation doesn't assume a default service
  account.

The `Automation` resource is a child resource of the
[delivery pipeline](https://docs.cloud.google.com/deploy/docs/architecture#resources); if you
[delete a delivery pipeline](https://docs.cloud.google.com/deploy/docs/delete-pipeline), all automations that
are children of that pipeline are also deleted.

The [configuration file schema](https://docs.cloud.google.com/deploy/docs/config-files#automation_definitions)
describes how to configure the `Automation`.

## The `AutomationRun` resource

An `AutomationRun` represents an execution of an
[automation rule](https://docs.cloud.google.com/deploy/docs/automation-rules).

## The automation service account

The service account you use to invoke an automation can be the
[default service account](https://docs.cloud.google.com/deploy/docs/cloud-deploy-service-account#execution_service_account)
or another service account. However, even if you're using the default service
account, you must specify it, using the `serviceAccount` property in the
`Automation` configuration.

The automation service account must have `iam.serviceAccount.actAs` permission
on the
[applicable execution service account](https://docs.cloud.google.com/deploy/docs/cloud-deploy-service-account#execution_service_account).
Also, if the automation service account isn't in the same project as the
delivery pipeline, the Cloud Deploy
[service agent](https://docs.cloud.google.com/deploy/docs/cloud-deploy-service-account#service_agent) must
have `iam.serviceAccount.actAs` on the automation service account.

### Required permissions on the automation service account

Whether you specify the default or a non-default service account for an
automation, the service account must have the following permissions:

- Permission to `actAs` the
  [execution service account](https://docs.cloud.google.com/deploy/docs/cloud-deploy-service-account#execution_service_account).

- [Permissions](https://docs.cloud.google.com/deploy/docs/iam-roles-permissions#permissions) to perform the operations that are being automated. See the
  [automation rules](https://docs.cloud.google.com/deploy/docs/automation-rules) for specific permission
  requirements.

## What's next

- Try the [quickstart: Automate release creation and rollout advancement](https://docs.cloud.google.com/deploy/docs/deploy-app-automation).

- Read about [automation rules](https://docs.cloud.google.com/deploy/docs/automation-rules).