cmd+/

Set up Smart Deployments

Cloud

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 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 guide instead.

Prerequisites

Before you start, confirm the following:

A CircleCI account connected to your code. You can sign up for free.
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.

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 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:

In the CircleCI web app, select your org from the org cards on your user homepage.
Select Projects from the sidebar and locate your project from the list. You can use the search to help.
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.
Select Deploys in the sidebar.
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 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, 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 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

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.
Review the generated validation and deploy configuration. To check the generated commit without opening a pull request, select View commit.
Address any schema validation warnings shown in the guided setup before you merge.
Merge the pull request.
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 and 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:

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.

On the Connect monitoring step, select Generate webhook secret.
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:

{
  "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.

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

In Datadog, create or edit a webhook integration for alerts.
Set the webhook URL to the CircleCI ingest URL.
Add the bearer auth custom header.

Set the payload to include the provider, the alert transition, and your tags:

{
  "provider": "datadog",
  "alert_transition": "$ALERT_TRANSITION",
  "tags": "$TAGS"
}

Ensure your alert notifications include the tags listed below on every payload. Use the format tag_name:value in the tags array.

Table 1. Datadog tags CircleCI matches on
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

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

Table 2. Prometheus and Alertmanager labels CircleCI matches on
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:

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

Configure a custom monitoring tool

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

Table 3. Fields to include in a custom webhook payload
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:

{
  "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 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 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 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:

In the CircleCI web app, select your org from the org cards on your user homepage.
Select Org from the sidebar to open your organization settings page.
Select Deploys.
Find the Webhook secrets card. The table lists each secret with its name, creation date, last used date, and expiry date.
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.
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 page.
Customize your generated rollback pipeline. See the Set up Rollbacks guide.
Customize your generated deploy pipeline. See the Set up Deploys guide.
Learn how to roll back manually. See the Rollback a Deployment guide.
Define ordered promotion paths across your environments. See the Environment Hierarchy and Version Promotion guide.

[path]

[title]

Set up Smart Deployments

Prerequisites

Start the guided setup

1. Choose your protection level

1.1. Select continuous validation or deploy tracking

1.2. Configure automatic rollback

1.3. Select a monitoring provider

1.4. Review what is added to your configuration

2. Generate configuration and merge the pull request

2.1. Select the config branch

2.2. Generate the configuration

2.3. Review and merge the pull request

3. Connect monitoring webhooks

3.1. Copy the webhook ingest URL

3.2. Create a webhook secret

3.3. Authenticate webhook requests

3.4. Configure your monitoring provider

Configure Datadog

Configure Prometheus or Alertmanager

Configure a custom monitoring tool

3.5. Finish the setup

Check your first validated release

Manage Smart Deployments settings

Change your protection level

Manage webhook secrets

Next steps