---
title: "Set up Smart Deployments"
description: "Use the guided setup in the CircleCI web app to configure Smart Deployments, including release validation and automatic rollback, from one flow."
doc_version: "unversioned"
last_updated: "2026-08-06"
---

> For the complete documentation index, see [llms.txt](https://circleci.com/docs/llms.txt)

# Set up Smart Deployments

This guide shows how to configure Smart Deployments using the guided setup in the CircleCI web app. You answer a few questions, and CircleCI generates the configuration and opens a pull request for you to merge.

Smart Deployments is the CircleCI continuous validation feature. For more information, see the [Smart Deployments Overview](https://circleci.com/docs/guides/deploy/smart-deployments-overview/) page.

The guided setup configures deploy markers, release validation, rollback and deploy pipelines, and automatic rollback in one flow. It replaces working through the deploy marker, rollback pipeline, and deploy pipeline guides separately.

If your code is not in a GitHub repository, or your organization does not have AI features enabled, the guided setup is unavailable. Follow the [Set up Release Validation Manually](https://circleci.com/docs/guides/deploy/set-up-release-validation-manually/) guide instead.

## Prerequisites

Before you start, confirm the following:

*   A CircleCI account connected to your code. You can [sign up for free](https://circleci.com/signup/).
    
*   A CircleCI project with a workflow configured to deploy your code.
    
*   Your code must be stored in a **GitHub** repository. CircleCI installs the GitHub App in your organization during setup if it is not installed already. For more information, see the [Users, Organizations, and Integrations Guide](https://circleci.com/docs/guides/permissions-authentication/users-organizations-and-integrations-guide/).
    
    Only organization administrators can install the GitHub App.
    
*   AI features enabled for your organization, because the guided setup generates your configuration with AI. See the [Enable AI-Powered Features](https://circleci.com/docs/guides/toolkit/enable-ai-powered-features/) page for steps.
    
*   For continuous validation, a monitoring tool that can send outbound webhooks. Datadog and Prometheus-compatible tools are supported directly, and you can connect any other tool as a custom provider.
    

## Start the guided setup

You can start Smart Deployments from any of the following places in the web app:

*   Your project home page. Select **Smart Deployments**.
    
*   Your project deploys page, when the project has no deploys configured yet.
    
*   Your project settings. Select **Deploys** in the sidebar, then select **Smart Deployments** in the Smart Deployments card.
    

To reach the project settings entry point, follow these steps:

1.  In the [CircleCI web app](https://app.circleci.com), select your org from the org cards on your user homepage.
    
2.  Select **Projects** from the sidebar and locate your project from the list. You can use the search to help.
    
3.  Select the ellipsis next to your project and select **Project Settings**.
    
    You can also access project settings from each project overview page using the **Settings** button.
    
4.  Select **Deploys** in the sidebar.
    
5.  Select **Smart Deployments**.
    

## 1\. Choose your protection level

The first step of the guided setup asks how much protection you want, and which monitoring tool sends the signals.

### 1.1. Select continuous validation or deploy tracking

Select **Continuous validation**, marked **Suggested**, to validate every release against your monitoring tool. Select **Deploy tracking** to log your deploys and set up the pipelines without validating anything.

Both levels generate deploy markers, a rollback pipeline, and a deploy pipeline. The difference is that continuous validation also adds a validation policy, so the release validation engine decides whether each release is healthy.

If you select deploy tracking, the guided setup skips monitoring provider selection and the Connect monitoring step. You can return later and add a validation policy to your configuration.

### 1.2. Configure automatic rollback

Leave **Auto rollback on failure** enabled unless you want failure detection without an automatic revert. When the toggle is enabled, CircleCI attempts a rollback to the last healthy version if validation fails during the evaluation window.

You can also change this setting later in your configuration file. See the [Optional Validation Fields](https://circleci.com/docs/guides/deploy/release-validation-reference/#optional-validation-fields) section.

### 1.3. Select a monitoring provider

Choose the provider that sends your validation webhooks:

*   Datadog
    
*   Prometheus
    
*   Custom
    

You must select a provider before you continue. Provider-specific webhook instructions appear in [step 3.4](#3-4-configure-your-monitoring-provider), after you merge the configuration pull request. You can also finish the webhook setup later from your organization deploy settings.

### 1.4. Review what is added to your configuration

Expand **What we’ll add to your config** to see the changes CircleCI generates:

*   Deploy markers in `.circleci/config.yml`.
    
*   A `validation` block on your release job in `.circleci/config.yml`.
    
*   A rollback pipeline in `.circleci/rollback.yml`.
    
*   A deploy pipeline in `.circleci/deploy.yml`.
    

The guided setup generates a starting configuration. You can extend it once you have reviewed the pull request. For every field you can set, see the [Release Validation Configuration Reference](https://circleci.com/docs/guides/deploy/release-validation-reference/) page.

Select **Generate configuration** to continue.

## 2\. Generate configuration and merge the pull request

In this step CircleCI writes the generated configuration to a branch in your repository, and you review and merge it.

### 2.1. Select the config branch

Choose the branch that contains your `.circleci/config.yml` file. CircleCI commits the generated configuration to a branch called `circleci/deploy-setup` and targets the branch you select.

The **Ready to generate** panel confirms which configurations the pull request includes.

### 2.2. Generate the configuration

Select **Generate configuration**. CircleCI generates each configuration in turn and shows its progress. Generation takes a few moments.

CircleCI generates the following:

*   Deploy markers and a `validation` block in `.circleci/config.yml`.
    
*   A rollback pipeline in `.circleci/rollback.yml`, when you selected that option.
    
*   A deploy pipeline in `.circleci/deploy.yml`, when you selected that option.
    

### 2.3. Review and merge the pull request

1.  Select **Create pull request on GitHub**. This opens GitHub with a pull request titled **Configure deploy settings**, from `circleci/deploy-setup` to the branch you selected. The pull request description contains a pre-filled verification checklist.
    
2.  Review the generated validation and deploy configuration. To check the generated commit without opening a pull request, select **View commit**.
    
3.  Address any schema validation warnings shown in the guided setup before you merge.
    
4.  Merge the pull request.
    
5.  Return to the guided setup and select **I’ve merged the pull request**.
    

Once you confirm the merge, CircleCI creates the rollback and deploy pipeline definitions in your project settings.

Review the generated pipelines against your deployment process before you rely on them. The generated rollback and deploy configuration is a starting point, and you will usually need to add your own authentication and deployment logic. See the [Example Rollback Pipeline Configuration](https://circleci.com/docs/guides/deploy/set-up-rollbacks/#example-rollback-pipeline-configuration) and [Example Deploy Pipeline Configuration](https://circleci.com/docs/guides/deploy/set-up-deploys/#example-deploy-pipeline-configuration) sections.

## 3\. Connect monitoring webhooks

This step is required for continuous validation. Without it, the engine receives no signals, so every release passes without being checked.

### 3.1. Copy the webhook ingest URL

On the **Connect monitoring** step, copy the webhook ingest URL. CircleCI shows the full URL with your organization ID already filled in:

```text
https://circleci.com/api/v3/deploy/hooks/<org-id>/validate
```

All validation webhooks POST to this URL. It is the same for every webhook secret in your organization.

### 3.2. Create a webhook secret

CircleCI authenticates validation webhooks with a bearer token.

1.  On the **Connect monitoring** step, select **Generate webhook secret**.
    
2.  Copy the secret immediately. You cannot view it again after you leave the screen.
    

CircleCI names the secret `validation-webhook`. Each additional generated secret takes a numbered suffix, so the next is `validation-webhook-2`, then `validation-webhook-3`.

The plaintext token is shown once. Store it in your monitoring tool or your secrets manager straight away. If you lose it, revoke the secret and create a new one.

### 3.3. Authenticate webhook requests

Configure your monitoring tool to send the following custom header on every validation webhook:

```json
{
  "Authorization": "Bearer <secret>"
}
```

Replace `<secret>` with the token you copied. Do not include the angle brackets.

### 3.4. Configure your monitoring provider

Follow the instructions for the provider you selected in [step 1.3](#1-3-select-a-monitoring-provider).

Each provider needs the ingest URL, the bearer auth header, and a set of tags that let CircleCI match the alert to the right release.

#### Configure Datadog

1.  In Datadog, create or edit a webhook integration for alerts.
    
2.  Set the webhook URL to the CircleCI ingest URL.
    
3.  Add the bearer auth custom header.
    
4.  Set the payload to include the provider, the alert transition, and your tags:
    
    ```json
    {
      "provider": "datadog",
      "alert_transition": "$ALERT_TRANSITION",
      "tags": "$TAGS"
    }
    ```
    
5.  Ensure your alert notifications include the tags listed below on every payload. Use the format `tag_name:value` in the `tags` array.
    

| Tag | Required | Purpose |
| --- | --- | --- |
| `component_name` | Yes | The component for the release under validation. |
| `env` | Yes | The environment, for example `production`. |
| `signal_name` | Yes, when using named webhooks | Must match a `validation.webhooks[].name` value in your configuration. This routes the alert to the correct check when a release has more than one check. |
| `version` | No | The deployed version. Omit this tag only if you accept fan-out to all matching running releases. |
| `project_id` | No | The CircleCI project UUID. Omit this tag to match any project that shares the same component and environment. |
| `namespace` | No | The component instance namespace. Omit this tag to match any namespace for that component and environment. |

Map your Datadog template variables so that `component_name`, `version`, `env`, and `signal_name` align with the values your deploy markers use.

For Datadog, the engine also accepts the monitor tags `app:<name>` and `service:<name>` as aliases for `component_name`, and `environment:<name>` as an alias for `env`. Prefer the canonical names.

#### Configure Prometheus or Alertmanager

1.  In Prometheus or Alertmanager, create or edit a webhook receiver.
    
2.  Set the URL to the CircleCI ingest URL.
    
3.  Add the bearer auth custom header.
    
4.  Include the keys listed below under `groupLabels` in the webhook payload.
    

| Label | Purpose |
| --- | --- |
| `alertname` | The validation signal name. This must match a `validation.webhooks[].name` value in your configuration. |
| `component_name` | The component for the release under validation. |
| `env` | The environment. |
| `version` | The deployed version. |

Check that your payload shape matches the following example:

```json
{
  "provider": "prometheus",
  "status": "firing",
  "groupLabels": {
    "alertname": "error_rate",
    "component_name": "my-service",
    "env": "production",
    "version": "1.0.0"
  }
}
```

#### Configure a custom monitoring tool

1.  Configure an alert webhook in your monitoring tool.
    
2.  POST to the CircleCI ingest URL with the bearer auth custom header.
    
3.  Send a JSON body that includes the fields listed below.
    

| Field | Purpose |
| --- | --- |
| `provider` | Set this to `custom`. |
| `component_name` | The application or component name. |
| `env` | The environment. |
| `signal_name` | The validation signal. This must match a `validation.webhooks[].name` value in your configuration. |
| `version` | The deployed version. |
| `alert_transition` | The condition signal, for example `triggered`. |

Check that your payload shape matches the following example:

```json
{
  "provider": "custom",
  "component_name": "my-service",
  "version": "1.0.0",
  "env": "production",
  "signal_name": "error_rate",
  "alert_transition": "triggered"
}
```

If your monitoring tool sends payloads in a different shape, map the fields explicitly in your configuration. See the [Data Point Keys](https://circleci.com/docs/guides/deploy/release-validation-reference/#data-point-keys) section.

### 3.5. Finish the setup

Select **Done** to finish the guided setup.

Your next deploy through the release job starts an evaluation window and waits for signals from your monitoring tool. To check that your webhook works, trigger a test alert in your monitoring tool and look for the event in the Release Validation panel on your deployment details page.

If you closed the guided setup before you connected your monitoring tool, you can finish the webhook setup at any time from your organization deploy settings.

## Check your first validated release

Your next deploy through the release job starts an evaluation window and waits for signals from your monitoring tool.

Open the deployment from the deploys timeline and find its Release Validation panel. The panel shows the evaluation deadline and each check in a **Listening** state, then records each webhook event as it arrives.

For what each outcome means, and what the panel shows, see the [How Release Validation Works](https://circleci.com/docs/guides/deploy/smart-deployments-overview/#how-release-validation-works) section.

## Manage Smart Deployments settings

### Change your protection level

Your protection level is a configuration setting, not a one-time choice. To move from deploy tracking to continuous validation, or to turn validation off, edit the `validation` block on your release job. See the [Release Validation Configuration Reference](https://circleci.com/docs/guides/deploy/release-validation-reference/) page.

You can also run the guided setup again from project settings.

### Manage webhook secrets

To view, create, or revoke webhook secrets, follow these steps:

1.  In the [CircleCI web app](https://app.circleci.com), select your org from the org cards on your user homepage.
    
2.  Select **Org** from the sidebar to open your organization settings page.
    
3.  Select **Deploys**.
    
4.  Find the Webhook secrets card. The table lists each secret with its name, creation date, last used date, and expiry date.
    
5.  Select **Create webhook secret** to add one. Enter a descriptive name, for example `Production Datadog`, and optionally set an expiration date. Copy the plaintext token before you close the modal.
    
6.  Select **Revoke** to revoke a secret.
    

Secrets created by the guided setup are named `validation-webhook`, then `validation-webhook-2`, `validation-webhook-3`, and so on for each one after that. Secrets you create yourself keep the name you give them, so use a descriptive name if you run several monitoring tools.

Revoking a secret takes effect immediately. Any monitoring tool still sending that token stops being able to deliver validation webhooks, so update your monitoring tool before you revoke.

## Next steps

*   Extend your generated validation configuration with named checks, custom fail criteria, and explicit field mappings. See the [Release Validation Configuration Reference](https://circleci.com/docs/guides/deploy/release-validation-reference/) page.
    
*   Customize your generated rollback pipeline. See the [Set up Rollbacks](https://circleci.com/docs/guides/deploy/set-up-rollbacks/) guide.
    
*   Customize your generated deploy pipeline. See the [Set up Deploys](https://circleci.com/docs/guides/deploy/set-up-deploys/) guide.
    
*   Learn how to roll back manually. See the [Rollback a Deployment](https://circleci.com/docs/guides/deploy/rollback-a-deployment/) guide.
    
*   Define ordered promotion paths across your environments. See the [Environment Hierarchy and Version Promotion](https://circleci.com/docs/guides/deploy/environment-hierarchy-and-version-promotion/) guide.