Documentation structure for LLMs (llms.txt)
CircleCI Logo

Smart Deployments overview

1 minute ago
Cloud

Smart Deployments is the CircleCI continuous validation feature. It decides whether a deployment is healthy, and gates the release on that outcome.

Smart Deployments works through the release validation engine. The engine listens for signals from the monitoring tools you already run, then evaluates them against a policy in your CI/CD configuration. It marks the release as a success or a failure, and triggers your rollback pipeline when a release fails.

Quickstart

To get set up right away, choose your route:

Your situation Start here

Your code is in a GitHub repository, and your organization has AI features enabled

Set up Smart Deployments. The guided setup generates your configuration and opens a pull request for you to merge.

Anything else

Set up Release Validation Manually. You write the validation policy and connect your monitoring tool yourself.

For every field you can set once you are configured, see the Release Validation Configuration Reference page.

How release validation works

  1. You trigger a release whose configuration includes a validation policy.

  2. CircleCI creates a validation plan and opens an evaluation window.

  3. Your monitoring tool sends alert webhooks to the engine during the window.

  4. The engine evaluates each signal against your failure criteria.

  5. If the criteria are met, the release fails. If the window closes first, the release succeeds.

When a release fails and your project has a rollback pipeline configured, the engine triggers that pipeline for you, targeting the last successful release.

flowchart TD Deploy([Deploy completes]) --> Window[Engine opens
evaluation window] Window --> Signal[Monitoring tool
sends alert webhook] Signal --> Criteria{Failure criteria met?} Criteria -->|No| Open{Window still open?} Open -->|Yes| Signal Open -->|No| Pass([Release succeeds]) Criteria -->|Yes| Fail[Release marked failed] Fail -->|If configured| Rollback[Rollback pipeline targets
last successful release] Rollback --> Restored([Last successful
release restored])
Figure 1. How the release validation engine gates a release

Validation outcomes

Outcome What happens

Validation passes

The release completes successfully.

Validation fails

The release is marked failed. Automatic rollback may trigger.

Automatic rollback succeeds

The rollback pipeline runs and returns the component to the last successful release.

Automatic rollback fails

The failed rollback does not trigger another automatic rollback, even when the rollback pipeline includes validation of its own.

Automatic rollback skipped

No rollback runs. This happens when there is no prior successful release, or when no rollback pipeline is configured.

Manual promote

Validation ends early and the release is marked successful.

Manual cancel

Validation stops. A rollback may trigger if a prior version exists.

To end validation early, use the promote or cancel actions on the deployment details page. Promoting marks the release successful, so use it when you have confirmed the release is healthy by other means.

View validation results

Open a deployment from the deploys timeline to see its Release Validation panel. The panel shows the following:

  • The validation status, evaluation deadline, start time, and the number of validations and failures.

  • A progress bar for the evaluation window, with its start time and deadline.

  • Each validation plan, with its status, failure count against the maximum, and its fails when expression.

  • The webhook events received for each plan, and whether each event matched the fail criteria.

If validation fails, a banner at the top of the page names the plan that failed and the expression that matched.

Protection levels

Smart Deployments has two protection levels:

  • Continuous validation (suggested): Deploy markers, release validation, rollback and deploy pipelines, and automatic rollback.

  • Deploy tracking: Deploy markers plus rollback and deploy pipelines, without release validation or automatic rollback. CircleCI records what shipped and when, and you deploy and roll back from the web app yourself.

Both levels generate the same deploy markers, rollback pipeline, and deploy pipeline. Continuous validation adds the validation policy on top, so the engine decides release health instead of a person. You can start with deploy tracking and add validation later, because your protection level is a configuration setting rather than a one-time choice.

Choosing continuous validation gives you the following capabilities:

Capability Description

Deploy markers

Records when your deploys start and finish. Every other capability requires deploy markers.

Release validation

Evaluates webhook signals from your monitoring tool during an evaluation window after each deploy.

Rollback and deploy pipelines

Rollback and deploy workflows you can trigger from the web app. Required for automatic rollbacks.

Automatic rollback

Reverts to the last successful release when validation fails, using your rollback pipeline. Optional, and enabled by default.

Benefits of Smart Deployments

You define a policy, point a monitor at a webhook URL, and CircleCI determines release health for you.

No specialized infrastructure

Gate releases without Kubernetes, Argo Rollouts, or the CircleCI release agent. The engine builds on the release management you already have.

Works with your existing tools

The engine has built-in support for Datadog and for Prometheus-compatible tools such as Alertmanager, plus a custom provider for any tool that can send an HTTP POST. You reuse the monitors you already operate.

Automated rollback

When a release breaches your policy, the engine triggers your rollback pipeline and sets the target back to the last successful release.

Real-time gating

The engine evaluates alert signals as they arrive. It does no polling, and needs no extra infrastructure to operate.

Built-in visibility

Validation status and the full event timeline appear on the release details page in the web app.

When to use Smart Deployments

Use Smart Deployments when any of the following apply:

  • You want deployment safety without adopting a service mesh or a progressive delivery stack.

  • You already run monitors, and you want them to decide whether a release is healthy.

  • You want failed releases to roll back without manual intervention.

  • You prefer one declarative policy in your configuration over custom health-check scripts.

Concepts

Validation policy

A validation policy is the declarative definition of release health that you add to your CI/CD configuration. It sets how long to listen, what counts as a failure, and how many failures to tolerate.

You configure the policy under a validation key on your release job. For every field, see the Release Validation Configuration Reference page.

Validation plan

A validation plan is one instance of a check for one release. CircleCI creates the plans from your policy when the release starts, and each plan tracks its own status, event history, and failure count.

The engine matches each incoming webhook to a plan using the component, environment, and check name that the webhook carries. For the full matching rules, see the Data Point Keys section.

Evaluation window

The evaluation window is the period after a deploy completes during which the engine accepts signals. When the window closes without a failure, the release succeeds. The default window is 20 minutes, and you set your own with evaluation_time.

Match the window to how quickly your monitors fire. A window shorter than your monitor evaluation interval closes before any signal can arrive, so the release passes without ever being checked.

Smart Deployments and the release agent

Smart Deployments is the route to release management for most projects, whatever you deploy to. It needs no cluster access and no agent installed.

The CircleCI Release Agent remains the option for teams who want Kubernetes-native controls, such as scaling and restarting components from the web app, or progressive delivery with Argo Rollouts. Choose the release agent when you need those controls, not as a prerequisite for gating releases.

Do not use both Smart Deployments and the CircleCI release agent in the same project.

Get started