Skip to content

Deployment Gates: add conceptual info to root page, delete Explore page #41267

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
clreaume wants to merge 1 commit into
base: master
Choose a base branch
from
+84 −70
Open

Deployment Gates: add conceptual info to root page, delete Explore page #41267

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 0 additions & 5 deletions hugo/config/_default/menus/main.en.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6193,11 +6193,6 @@ menu:
parent: deployment_gates_setup
identifier: deployment_gates_setup_preconfigured
weight: 2
- name: Explore
url: deployment_gates/explore/
parent: deployment_gates
identifier: deployment_gates_explore
weight: 2
- name: Test Optimization
url: tests/
pre: ci
Expand Down
86 changes: 77 additions & 9 deletions hugo/content/en/deployment_gates/_index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,13 +1,12 @@
---
title: Deployment Gates
description: "Reduce deployment incidents by automatically evaluating monitors and APM anomalies to halt releases when performance regressions are detected."
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."
aliases:
- /deployment_gates/explore
further_reading:
- link: "/deployment_gates/setup"
tag: "Documentation"
text: "Set up Deployment Gates"
- link: "/deployment_gates/explore"
tag: "Documentation"
text: "Learn about the Deployment Gates explorer"
- link: "continuous_delivery"
tag: "Documentation"
text: "Learn about Continuous Delivery Visibility"
Expand All @@ -20,17 +19,86 @@ algolia:

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 the new changes by using [monitors][1] and APM anomalies.
When anomalies or performance regressions are detected, you can automatically halt the release, preventing unstable code from reaching a wider user base. Additionally, you can then use Deployment Gates as the entry-point to investigate the problem.
When performing a production rollout, you can use Deployment Gates to evaluate the impact of new changes with [monitors][1] and [APM Faulty Deployment Detection][4]. 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.

{{< img src="/deployment_gates/explore/deployment_gates_explorer.png" alt="The Deployment Gate evaluation page in Datadog" style="width:100%" >}}

@joepeeples joepeeples Nov 3, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
{{< img src="/deployment_gates/explore/deployment_gates_explorer.png" alt="The Deployment Gate evaluation page in Datadog" style="width:100%" >}}
{{< img src="/deployment_gates/explore/deployment_gates_explorer.png" alt="The Deployment Gates Evaluations page, listing recent gate evaluations with their status and failing rules" style="width:100%" >}}

When the screenshot is updated, remember to update the alt text to match.


For setup instructions, see [Set up Deployment Gates][2].

## How Deployment Gates work

A Deployment Gate has two main components:

- **Gate**: A gate, defined for a given service and environment, evaluates one or more rules to decide whether a deployment should proceed.

@joepeeples joepeeples Nov 3, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
- **Gate**: A gate, defined for a given service and environment, evaluates one or more rules to decide whether a deployment should proceed.
- **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](#rules) checks the status of one or more [monitors][1] or runs [APM Faulty Deployment Detection][4] 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

A gate's configuration source is where the gate is defined: in the evaluation request itself, or in Datadog ahead of time.

@joepeeples joepeeples Nov 3, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This reads a little awkwardly to me; hopefully this isn't too wordy:

Suggested change
A gate's configuration source is where the gate is defined: in the evaluation request itself, or in Datadog ahead of time.
A gate's configuration source refers to how the gate is defined: in the evaluation request itself, or in Datadog ahead of time.


- **JIT**: A Just-In-Time (JIT) Deployment Gate is defined in your deployment configuration, such as a JSON configuration file passed to the [`datadog-ci` CLI][5] or the payload of an API call, and sent with each evaluation request. There is no setup in Datadog.

@joepeeples joepeeples Nov 3, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Longish sentence; maybe this works to break it up, but check to make sure it's the "configuration" that's sent with each request, or if we need a more precise term here:

Suggested change
- **JIT**: A Just-In-Time (JIT) Deployment Gate is defined in your deployment configuration, such as a JSON configuration file passed to the [`datadog-ci` CLI][5] or the payload of an API call, and sent with each evaluation request. There is no setup in Datadog.
- **JIT**: A Just-In-Time (JIT) Deployment Gate is defined in your deployment configuration, such as a JSON configuration file passed to the [`datadog-ci` CLI][5] 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.

| | JIT | Preconfigured |

@joepeeples joepeeples Nov 3, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This table is helpful in distinguishing the gate types, but it could use some kind of intro/lead-in above it for smoother flow.

|---|---|---|
| **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 identifier, which reference the preconfigured gate |

@joepeeples joepeeples Nov 3, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
| **What the evaluation request contains** | The full gate configuration, including service, environment, and rules | Service, environment, and optionally identifier, which reference the preconfigured gate |
| **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 |
| **Evaluations shown on [Evaluations][6] page?** | Yes | Yes |

@joepeeples joepeeples Nov 3, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The "Evaluations shown on Evaluations page?" row has the same answer for both configuration sources, so it doesn't help readers compare them. Line 81 already says where evaluations are recorded. Consider removing the row.

Suggested change
| **Evaluations shown on [Evaluations][6] page?** | Yes | 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 JIT gates. They require no setup in Datadog, and you can iterate on rules directly in your deployment configuration.

## 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 all of them must pass for the gate to pass (when the gate and its rules are in [active mode](#evaluation-modes)). 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.

@joepeeples joepeeples Nov 3, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
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 all of them must pass for the gate to pass (when the gate and its rules are in [active mode](#evaluation-modes)). 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.
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 a gate passes only if all of its [active](#evaluation-modes) 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](#rule-types) and options specific to its type. Rules belong to the gate's [configuration source](#configuration-sources): JIT 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](#evaluation-modes) 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

Deployment Gates support two rule types:

- [Monitor][1]: Checks the state of one or more [monitors][1] over a configurable period of up to two hours. The rule fails if a monitor enters an `Alert` or `No Data` status during that period. Indicate the monitor(s) to check using a monitor search query or by providing a monitor ID.

@joepeeples joepeeples Nov 3, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
- [Monitor][1]: Checks the state of one or more [monitors][1] over a configurable period of up to two hours. The rule fails if a monitor enters an `Alert` or `No Data` status during that period. Indicate the monitor(s) to check using a monitor search query or by providing a monitor ID.
- [Monitor][1]: 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 a monitor ID.

- [APM Faulty Deployment Detection][4]: Uses [Watchdog][7] 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 two hours.

@joepeeples joepeeples Nov 3, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
- [APM Faulty Deployment Detection][4]: Uses [Watchdog][7] 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 two hours.
- [APM Faulty Deployment Detection][4]: Uses [Watchdog][7] 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

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.

@joepeeples joepeeples Nov 3, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
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.
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 a [JIT](#configuration-sources) gate, the request also contains the gate's rules. For a [preconfigured](#configuration-sources) 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.
2. **Datadog starts the evaluation.** The API immediately returns an evaluation ID, and each rule runs for its configured duration.
3. **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][5] and the [GitHub Action][8] handle polling for you: they wait until the evaluation completes or a configurable timeout is reached.
4. **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][6] page. Here, you can also identify frequently failing rules and gates and track patterns over time.

@joepeeples joepeeples Nov 3, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
Each evaluation and its per-rule results, including the reason a rule failed, are recorded on the [Deployment Gates Evaluations][6] page. Here, you can also identify frequently failing rules and gates and track patterns over time.
Each evaluation and its per-rule results, including the reason a rule failed, are recorded on the [{{< ui >}}Deployment Gates Evaluations{{< /ui >}}][6] page. On this page, you can also identify frequently failing rules and gates and track patterns over time.


### 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][6] 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.

@joepeeples joepeeples Nov 3, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
- **Dry run**: The result is recorded on the [Evaluations][6] 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**: The result is recorded on the [Evaluations][6] 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.


For setup instructions, see [Set up Deployment Gates][2]. After the setup is completed, you can track and analyze gate evaluations through the [Deployment Gates Evaluations][3] page:
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.

{{< img src="/deployment_gates/explore/deployment_gates_explorer.png" text="The Deployment Gate evaluation page in Datadog" style="width:100%" >}}
For JIT 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 {{< ui >}}Evaluation Mode{{< /ui >}} setting on the gate or rule.

## Further reading

{{< partial name="whats-next/whats-next.html" >}}

[1]: /monitors/

@joepeeples joepeeples Nov 3, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The URL references skip [3], consider renumbering & reordering all the URLs (Claude's good at this)

[2]: /deployment_gates/setup
[3]: /deployment_gates/explore
[4]: /watchdog/faulty_deployment_detection/
[5]: https://github.com/DataDog/datadog-ci/tree/master/packages/plugin-deployment#gate
[6]: https://app.datadoghq.com/ci/deployment-gates/evaluations
[7]: /watchdog
[8]: https://github.com/DataDog/deployment-gate-github-action
24 changes: 0 additions & 24 deletions hugo/content/en/deployment_gates/explore.md
View file
Open in desktop

This file was deleted.

33 changes: 7 additions & 26 deletions hugo/content/en/deployment_gates/setup/_index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,46 +1,27 @@
---
title: Set Up Deployment Gates
description: "Compare Just-In-Time (JIT) and preconfigured Deployment Gates and follow the setup walkthrough for your chosen mode."
description: "Compare Just-In-Time (JIT) and preconfigured Deployment Gates and follow the setup walkthrough for your chosen configuration source."
further_reading:
- link: "/deployment_gates/setup/jit"
tag: "Documentation"
text: "Set up Just-In-Time (JIT) Deployment Gates"
- link: "/deployment_gates/setup/preconfigured"
tag: "Documentation"
text: "Set up preconfigured Deployment Gates"
Comment on lines 5 to 10

@joepeeples joepeeples Nov 3, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

These links duplicate the nextlink links added below. Remove them here, as the nextlink links provide more detail

- link: "/deployment_gates/explore"
tag: "Documentation"
text: "Learn about the Deployment Gates explorer"
- link: "/api/latest/deployment-gates"
tag: "API Reference"
text: "Deployment Gates API reference"
---

Deployment Gates have two main components:

- A **Gate** is defined for a service and environment (and optionally an identifier), and evaluates one or more rules to decide whether a deployment should proceed.
- A **Rule** is a type of evaluation performed as part of a gate, such as checking the status of a set of monitors or running APM Faulty Deployment Detection analysis on the deployed version.

Gate evaluations are asynchronous — the API returns immediately with an evaluation ID, and the result resolves to `pass` or `fail` over time as the rules run.

## Deployment Gate evaluation modes
Deployment Gates support two evaluation modes: Just-In-Time (JIT) and preconfigured.


| | **[JIT][1]** (default) | **[Preconfigured][2]** |
|---|---|---|
| **Where rules live** | Inline in your deployment configuration or CI step | Persisted in Datadog (UI, API, or Terraform) |
| **Setup in Datadog** | None | Create a gate and rules ahead of time |
| **Best for** | Rules-as-code, per-deployment flexibility, teams that own their own gate configuration | Shared rules across services, central management, non-CI editing |
| **How to evaluate** | Send rules in the evaluation request | Reference the gate by service, environment, and optionally identifier |

You can use different modes across different gates if needed.
Choose where your Deployment Gates are defined, then follow the setup instructions. For a comparison of the two configuration sources, see [Configuration sources][1].

If you're unsure where to start, use JIT. It requires no setup in Datadog and lets you iterate on rules directly in your deployment configuration.
{{< whatsnext desc="Set up Deployment Gates:" >}}
{{< nextlink href="/deployment_gates/setup/jit" >}}<u>Just-In-Time (JIT)</u>: Define gates and rules in your deployment configuration, with no setup in Datadog.{{< /nextlink >}}
{{< nextlink href="/deployment_gates/setup/preconfigured" >}}<u>Preconfigured</u>: Create gates and rules in Datadog with the UI, API, or Terraform.{{< /nextlink >}}
{{< /whatsnext >}}

## Further reading

{{< partial name="whats-next/whats-next.html" >}}

[1]: /deployment_gates/setup/jit
[2]: /deployment_gates/setup/preconfigured
[1]: /deployment_gates/#configuration-sources
3 changes: 0 additions & 3 deletions hugo/content/en/deployment_gates/setup/jit.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,9 +5,6 @@ further_reading:
- link: "/deployment_gates/setup/preconfigured"
tag: "Documentation"
text: "Set up preconfigured Deployment Gates"
- link: "/deployment_gates/explore"
tag: "Documentation"
text: "Learn about the Deployment Gates explorer"
- link: "/api/latest/deployment-gates"
tag: "API Reference"
text: "Deployment Gates API reference"
Expand Down
3 changes: 0 additions & 3 deletions hugo/content/en/deployment_gates/setup/preconfigured.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,9 +5,6 @@ further_reading:
- link: "/deployment_gates/setup/jit"
tag: "Documentation"
text: "Set up Just-In-Time (JIT) Deployment Gates"
- link: "/deployment_gates/explore"
tag: "Documentation"
text: "Learn about the Deployment Gates explorer"
- link: "/api/latest/deployment-gates"
tag: "API Reference"
text: "Deployment Gates API reference"
Expand Down
Loading