--- title: Deployment Gates description: >- Reduce deployment incidents by evaluating monitors and APM Faulty Deployment Detection during a rollout, so your pipeline can halt releases when regressions are detected. breadcrumbs: Docs > Deployment Gates --- > For the complete documentation index, see [llms.txt](https://docs.datadoghq.com/llms.txt). # Deployment Gates {% callout %} # Important note for users on the following Datadog sites: app.ddog-gov.com, us2.ddog-gov.com {% alert level="danger" %} This product is not supported for your selected [Datadog site](https://docs.datadoghq.com/getting_started/site.md). ({% placeholder "user-datadog-site-name" /%}). {% /alert %} {% /callout %} Deployment Gates allow you to reduce the likelihood and impact of incidents caused by deployments. When performing a production rollout, you can use Deployment Gates to evaluate the impact of new changes with [monitors](https://docs.datadoghq.com/monitors.md) and [APM Faulty Deployment Detection](https://docs.datadoghq.com/watchdog/faulty_deployment_detection.md). When your gate detects a performance regression, you can automatically halt the release, preventing unstable code from reaching a wider user base. You can then use Deployment Gates as the entry point to investigate the problem. {% image source="https://docs.dd-static.net/images/deployment_gates/explore/deployment_gates_explorer.5ba87fde3a5435208268b2a1d360f435.png?auto=format&fit=max&w=850 1x, https://docs.dd-static.net/images/deployment_gates/explore/deployment_gates_explorer.5ba87fde3a5435208268b2a1d360f435.png?auto=format&fit=max&w=850&dpr=2 2x" alt="The Deployment Gates Evaluations page, listing recent gate evaluations with their status and failing rules" /%} For setup instructions, see [Set up Deployment Gates](https://docs.datadoghq.com/deployment_gates/setup.md). ## How Deployment Gates work{% #how-deployment-gates-work %} A Deployment Gate has two main components: - **Gate**: Defined for a given service, environment, and optional identifier, a gate evaluates one or more rules to decide whether a deployment should proceed. - **Rule**: A rule checks the status of one or more [monitors](https://docs.datadoghq.com/monitors.md) or runs [APM Faulty Deployment Detection](https://docs.datadoghq.com/watchdog/faulty_deployment_detection.md) on the deployed version. The outcome determines whether the associated gate should pass or fail. Although a gate reports whether a regression is detected, it doesn't stop a deployment on its own. After receiving a gate evaluation result, your deployment pipeline decides what to do next—for example, halting the deployment, performing a rollback, or alerting your team. ### Configuration sources{% #configuration-sources %} A gate's configuration source refers to how the gate is defined: in the evaluation request itself, or in Datadog ahead of time. - **Inline**: An inline Deployment Gate is defined in your deployment configuration, such as a JSON configuration file passed to the [`datadog-ci` CLI](https://github.com/DataDog/datadog-ci/tree/master/packages/plugin-deployment#gate) or the payload of an API call. The configuration is sent with each evaluation request. There is no setup in Datadog. - **Preconfigured**: A preconfigured Deployment Gate is created ahead of time in Datadog, then referenced in an evaluation request. Use the following table to choose the right source for your gate: | Inline | Preconfigured | | ----------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- | | **Where the gate is defined** | In your deployment configuration or CI step | In Datadog | | **Setup in Datadog** | None | Create the gate and its rules before the first evaluation | | **What the evaluation request contains** | The full gate configuration, including service, environment, and rules | Service, environment, and optionally an identifier, which identify the preconfigured gate | | **Does the gate have an ID?** | No, the gate exists only within each evaluation | Yes, the gate persists between evaluations | | **Shown on the [Evaluations](https://app.datadoghq.com/ci/deployment-gates/evaluations) page?** | Yes, even though the gate isn't stored in Datadog | Yes | | **Best for** | Managing rules as code alongside your pipeline, and teams that own their own gate configuration | Sharing rules across services, managing gates centrally, and editing rules outside of CI | You can use different configuration sources for different gates. If you're unsure where to start, use inline gates. They require no setup in Datadog, and you can iterate on rules directly in your deployment configuration. ## Rules{% #rules %} A rule is a check that a Deployment Gate runs to decide whether a deployment can proceed. Each gate contains one or more rules, and an active gate passes only if all of its active rules pass. When your pipeline requests a gate evaluation, Datadog evaluates each rule against the service, environment, and version being deployed. Each rule resolves to `pass` or `fail`, and the gate's result is based on those outcomes. Each rule has a type and options specific to its type. Rules belong to the gate's configuration source: inline gates send their rules with each evaluation request, and preconfigured gates keep their rules in Datadog. You can set an individual rule's evaluation mode to dry run, independently of the gate's evaluation mode. In an active gate, a dry run rule that fails is recorded but doesn't affect the gate's outcome. ### Rule types{% #rule-types %} Deployment Gates support two rule types: - [Monitor](https://docs.datadoghq.com/monitors.md): Checks the state of one or more monitors over a configurable period of up to 2 hours. The rule fails if a monitor enters an `Alert` or `No Data` status during that period. Specify the monitors to check with a monitor search query or monitor IDs. - [APM Faulty Deployment Detection](https://docs.datadoghq.com/watchdog/faulty_deployment_detection.md): Uses [Watchdog](https://docs.datadoghq.com/watchdog.md) to compare the deployed version against previous versions of the same service. The rule fails if the analysis detects new types of errors or a significant increase in error rates. The analysis runs over a configurable period of up to 2 hours. A gate can have one or more rules, including any combination of monitor and APM Faulty Deployment Detection rules. ## Evaluations{% #evaluations %} An evaluation is a single run of a gate's rules against a specific deployment. Evaluations are asynchronous: your pipeline triggers an evaluation, then checks back for the result while the rules run in the background. 1. **Your pipeline requests a gate evaluation.** The request identifies the service, environment, and version being deployed. For an inline gate, the request also contains the gate's rules. For a preconfigured gate, Datadog uses the service, environment, and optional identifier to find the gate. The version is required if the gate has an APM Faulty Deployment Detection rule. 1. **Datadog starts the evaluation.** The API immediately returns an evaluation ID, and each rule runs for its configured duration. 1. **Your pipeline polls for the result.** Your pipeline uses the evaluation ID to check the evaluation's status, which stays `in_progress` while the rules run. The [`datadog-ci` CLI](https://github.com/DataDog/datadog-ci/tree/master/packages/plugin-deployment#gate) and the [GitHub Action](https://github.com/DataDog/deployment-gate-github-action) handle polling for you: they wait until the evaluation completes or a configurable timeout is reached. 1. **The evaluation resolves to `pass` or `fail`.** The gate passes if all of its active rules pass, and fails if any active rule fails. Your pipeline then decides how to proceed based on the result. Each evaluation and its per-rule results, including the reason a rule failed, are recorded on the [Deployment Gates Evaluations](https://app.datadoghq.com/ci/deployment-gates/evaluations) page. On this page, you can also identify frequently failing rules and gates and track patterns over time. ### Evaluation modes{% #evaluation-modes %} Gates and rules each have an evaluation mode, which determines whether their results affect your deployment: - **Active**: The result counts. An active gate returns its actual result (`pass` or `fail`) to your pipeline, and an active rule's result counts toward the gate's result. - **Dry run**: The result is recorded on the [Evaluations](https://app.datadoghq.com/ci/deployment-gates/evaluations) page but doesn't affect your deployment. A dry run gate always returns `pass` to your pipeline, and a dry run rule's result is excluded from the gate's result. Dry run lets you see how a gate or rule behaves against real deployments before it can block one, which is useful when onboarding or adding a new rule. When the results match what you expect, switch to active. For inline gates, set the evaluation mode with the `dry_run` field in the evaluation request (`dryRun` in `datadog-ci` configuration files). For preconfigured gates, use the Evaluation Mode setting on the gate or rule. ## Further reading{% #further-reading %} Additional helpful documentation, links, and articles: - [Set up Deployment Gates](https://docs.datadoghq.com/deployment_gates/setup.md) - [Learn about Continuous Delivery Visibility](https://docs.datadoghq.com/continuous_delivery.md) - [Learn how to set up CD Visibility](https://docs.datadoghq.com/continuous_delivery/deployments.md)