> For the complete documentation index, see [llms.txt](https://developer.harness.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.harness.io/feature-management-experimentation/management-and-administration/pipeline-gated-changes.md).

# Pipeline-gated changes

Learn how to gate Harness FME feature flag and segment change requests through a Harness pipeline, and how to review those runs on the Pipeline Executions tab.

{% hint style="warning" %}
Pipeline gating is available only in the **New Experience**. It is not available in the **Classic Experience**.
{% endhint %}

**Restrict approval to pipeline** is an [environment-level approval mode](https://developer.harness.io/feature-management-experimentation/management-and-administration/environments.md#configure-approvals) in Harness FME. When an environment uses this mode, a change to a **feature flag definition** or a **segment definition** in that environment is not applied as soon as it is saved. Instead, the change request runs through a designated [Harness pipeline](https://developer.harness.io/feature-management-experimentation/management-and-administration/pipelines.md), and the pipeline decides whether the change is applied.

Pipeline gating covers both resource types equally. Everything on this page applies to feature flags and segments alike, and the payload identifies which one a change request targets through its `resourceType` field.

This is different from [adding FME steps to a pipeline](https://developer.harness.io/feature-management-experimentation/management-and-administration/pipelines.md#add-fme-steps-to-a-pipeline-stage). FME steps start in the pipeline and act on a flag. Pipeline gating starts in FME: a definition is edited as usual, whether through the FME UI or the FME APIs, and the resulting change request is routed through the pipeline for validation and approval.

Use pipeline gating when flag and segment changes in an environment need to pass automated checks or custom validations before they take effect, for example a PII review, a policy evaluation, a metric check, a ServiceNow approval raised by the pipeline, or a manual approval step owned by a release manager.

At a high level, a change to a feature flag definition or segment definition in a gated environment flows like this. The pipeline runs with the full before and after state of the definition plus any configured properties, and its result determines whether the change request is published or rejected:

```mermaid
flowchart TD
    A[Edit flag or segment] --> B[Review changes]
    B --> C[Change request created]
    C --> D[Gating pipeline runs]
    D --> E{Pipeline result}

    E -->|Succeeded| F[Published]
    F --> G[Definition updated]

    E -->|Failed| H[Rejected]
    H --> I[Definition unchanged]

    G --> J[Run listed on tab]
    I --> J
```

<br>

The rest of this page follows that sequence: how to [gate an environment](#gate-an-environment-through-a-pipeline), how to [submit a change](#submit-a-pipeline-gated-change), [what the pipeline receives](#what-the-pipeline-receives), and how to [review the result](#view-pipeline-executions-for-a-flag-or-segment).

## Before you begin

* You must be using the New Experience. See the note above.
* You need a Harness pipeline in the same project as the environment you want to gate. Go to [Create a Harness pipeline](https://developer.harness.io/feature-management-experimentation/management-and-administration/pipelines.md#create-a-harness-pipeline).
* You need permissions to edit FME environments, and the pipeline needs the permissions required to apply the change. Go to [Permissions](https://developer.harness.io/feature-management-experimentation/management-and-administration/pipelines.md#permissions).

## Gate an environment through a pipeline

Gating set on an environment applies to every feature flag and segment in that environment. A pipeline can also be set on an [individual feature flag or segment](#set-a-pipeline-on-a-single-flag-or-segment).

1. From the FME navigation menu, click **FME Settings** and select **Environments**.
2. Click **Edit** under the **Actions** column for the environment you want to gate.
3. Under **Change permissions**, select **Require approvals for changes**.
4. Select **Restrict approval to pipeline**.
5. For **Pipeline**, select the pipeline that gates changes for this environment. This is required: the environment cannot be saved in this mode without a pipeline.
6. Optionally define [properties](#pass-properties-to-the-pipeline) to pass to the pipeline.
7. Optionally enable **Allow kills without approval** so that emergency flag kills bypass the pipeline, and **Allow users in the selected group to skip approval flows**.
8. Optionally use **Who can withdraw a pending change** to let specific groups withdraw a pending change request in addition to the submitter.
9. Click **Save**.

Once saved, every feature flag definition and segment definition change in that environment is routed through the selected pipeline.

{% hint style="warning" %}
The bypass options above mean the pipeline does not run at all for the changes they cover. No pipeline execution is recorded and no automated approval record is created for those changes, so consider them carefully in environments where the pipeline is your audit trail.
{% endhint %}

### Pass properties to the pipeline

Properties are key-value pairs sent to the pipeline alongside the change request. Use them to carry context the pipeline needs but that FME does not track itself, such as a Jira ticket reference or a deployment target.

To add one, click **+ Add Property** and enter a **Key**. You can also set a **Default value** and mark the property as:

| Property kind | Behavior                                                                                                                                                                  |
| ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Optional**  | Shown on the change request by default. The submitter can edit the value or remove the property before submitting. This is the default when neither checkbox is selected. |
| **Required**  | Must carry a value. The submitter cannot remove it, and the change request cannot be submitted while the value is blank.                                                  |
| **Fixed**     | Locked to its configured value. The submitter can see it but cannot edit or remove it.                                                                                    |

You can define up to **5 properties per level**, meaning up to five on the environment and up to five on an individual feature flag or segment. A single change request can carry at most **10 properties** in total, including any added at submission time.

Configured properties arrive in the `properties` object of the [change request payload](#what-the-pipeline-receives), where the pipeline can reference them.

### Set a pipeline on a single flag or segment

A gating pipeline and its properties can also be set on an individual feature flag or segment, known as the **resource level**. The **Pipeline** field on the definition page reads `None` when no resource-level pipeline is set.

1. On the feature flag or segment definition page, click the edit icon next to the **Pipeline** field in the header. The **Pipeline** side panel opens.
2. Select a pipeline.
3. Optionally click **+ Add Property** to add a property. Enter a **Key** and an optional **Default value**, then select the **Required** or **Fixed** checkboxes as needed. Repeat for each property.
4. Click **Save**.

![The Pipeline side panel on a feature flag, with a pipeline selected and a property row](https://1473625385-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FrT2RGHAjtBTaObzchfpb%2Fuploads%2Fgit-blob-21a6135f8d633728a8918d869d3ee6ec46cffba4%2Fpipeline-gate-flag-panel.png?alt=media)

Once a pipeline is set, the **Pipeline** field shows its name and links to the pipeline. To remove the pipeline, click **Clear pipeline**.

### How environment and resource pipelines interact

When a pipeline is set at both levels, the two do not both run. The **environment pipeline takes precedence**: a resource-level pipeline runs only if the environment does not already have an approval restriction of its own.

Properties, by contrast, are merged into a single set for the change request:

* Environment properties are resolved first, then any resource-level keys that the environment does not define are appended.
* If both levels define the same key, the environment value wins when the environment property is **Fixed**, which carries over both its value and its locked status. Otherwise the resource-level value wins.
* **Required** is combined across levels. If either level marks a key as required, it is required on the change request.
* **Fixed** values are locked and override anything typed in by the submitter.
* A **Required** property with no default value and no value supplied blocks submission with a validation error.

The **Change summary** panel for a change request lists the merged set of properties that was sent to the pipeline.

## Submit a pipeline-gated change

Submitting a change is the same flow as any other FME change. Edit a feature flag definition or a segment definition and click **Review changes**.

In a pipeline-gated environment, the **Review changes** drawer shows a callout explaining that the environment is pipeline gated and that the change will be handed off to the pipeline rather than applied directly. The drawer also names the pipeline that will run and lists the [properties](#pass-properties-to-the-pipeline) that will be sent with the change request. Review the diff as you normally would, then submit.

Before submitting:

* Supply a value for any property marked **Required**. A required property with no value blocks submission.
* Properties marked **Fixed** are shown but cannot be edited or removed.
* Properties marked **Optional** can be edited, or removed from this change request.
* You can add a property that is not configured at either level by clicking **+ Add Property**. Keys may contain only letters, numbers, underscores, and hyphens, and cannot be blank. Properties added here count toward the limit of 10 properties per change request.

Once the change request is submitted and the pipeline is running, the change request shows the pipeline ID, the pipeline execution ID, and the properties that were sent.

For the standard approval modes, where a teammate or a fixed group of approvers reviews the change, go to [Approval flows](https://developer.harness.io/feature-management-experimentation/use-fme/feature-management/setup/approval-flows.md).

## What the pipeline receives

The gating pipeline is not limited to variables that the submitter fills in by hand. Harness FME sends the pipeline the full change request, including the complete before and after state of the definition, so the pipeline can inspect what actually changed and make a routing or approval decision based on it.

The change request is sent both as an object and as a string, for compatibility with older pipelines that do not support an object input type.

The payload is structured as follows:

<details>

<summary>Example change request payload</summary>

```json
{
  "changeRequest": {
    "id": "64762790-b2d1-11f1-b166-fe651682fb33",
    "status": "REQUESTED",
    "operationType": "UPDATE",
    "title": "",
    "requester": {
      "id": "5xCEvljNSMq00MUk8PRS0Q",
      "type": "USER",
      "name": "jane.doe@example.com"
    },
    "scope": {
      "accountIdentifier": "z_NVWUjlQ2-S8RqDnerR_g",
      "orgIdentifier": "pipeline_poc",
      "projectIdentifier": "pipeline_poc"
    },
    "environment": {
      "id": "664a4b10-89ef-11f1-a84c-2eef54553f57",
      "type": "ENVIRONMENT",
      "name": "Pipeline_test_env"
    },
    "comments": [],
    "resourceType": "FEATURE_FLAG_DEFINITION",
    "resourceId": "640effd0-8d0a-11f1-a1a2-3ae65e24f691",
    "before": {
      "id": "640effd0-8d0a-11f1-a1a2-3ae65e24f691",
      "featureFlag": {
        "id": "782b8130-4b2b-11f1-bd97-a2bd01141357",
        "name": "test_001"
      },
      "environment": {
        "id": "664a4b10-89ef-11f1-a84c-2eef54553f57",
        "name": "Pipeline_test_env"
      },
      "trafficType": {
        "id": "6d68d5e0-4b2b-11f1-bbff-d245ff45d791",
        "name": "user"
      },
      "isKilled": false,
      "treatments": [
        { "name": "on" },
        { "name": "off" },
        { "name": "test" }
      ],
      "defaultTreatment": "off",
      "trafficAllocation": 100,
      "rules": [],
      "defaultRule": [
        {
          "treatment": "off",
          "size": 100
        }
      ],
      "createdAt": "2026-07-31T18:05:19.309Z",
      "impressions": {}
    },
    "after": {
      "id": "640effd0-8d0a-11f1-a1a2-3ae65e24f691",
      "featureFlag": {
        "id": "782b8130-4b2b-11f1-bd97-a2bd01141357",
        "name": "test_001"
      },
      "environment": {
        "id": "664a4b10-89ef-11f1-a84c-2eef54553f57",
        "name": "Pipeline_test_env"
      },
      "trafficType": {
        "id": "6d68d5e0-4b2b-11f1-bbff-d245ff45d791",
        "name": "user"
      },
      "isKilled": false,
      "treatments": [
        { "name": "on" },
        { "name": "off" }
      ],
      "defaultTreatment": "off",
      "trafficAllocation": 100,
      "rules": [],
      "defaultRule": [
        {
          "treatment": "off",
          "size": 100
        }
      ],
      "createdAt": "2026-07-31T18:05:19.309Z",
      "impressions": {}
    },
    "properties": {
      "jiraTicket": "FME-111222",
      "env": "prod0"
    }
  }
}
```

</details>

| Field           | Description                                                                                                                                                                                                      |
| --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id`            | Unique identifier of the change request.                                                                                                                                                                         |
| `status`        | Current state of the change request, for example `REQUESTED`.                                                                                                                                                    |
| `operationType` | The kind of change being made, for example `UPDATE`.                                                                                                                                                             |
| `title`         | Optional title supplied by the submitter.                                                                                                                                                                        |
| `requester`     | The user who submitted the change, as a mini-object with `id`, `type`, and `name`.                                                                                                                               |
| `scope`         | The `accountIdentifier`, `orgIdentifier`, and `projectIdentifier` the change belongs to.                                                                                                                         |
| `environment`   | The FME environment the change targets.                                                                                                                                                                          |
| `comments`      | Comments attached to the change request.                                                                                                                                                                         |
| `resourceType`  | The type of resource being changed, which identifies whether the change targets a feature flag definition or a segment definition. The example above shows `FEATURE_FLAG_DEFINITION`.                            |
| `resourceId`    | Identifier of the specific definition being changed.                                                                                                                                                             |
| `before`        | The full definition as it exists today, including treatments, `defaultTreatment`, `trafficAllocation`, `rules`, and `defaultRule`.                                                                               |
| `after`         | The full definition as it would exist if the change is applied. Compare against `before` to determine exactly what changed.                                                                                      |
| `properties`    | The key-value [properties](#pass-properties-to-the-pipeline) configured on the environment and on the resource, [merged](#how-environment-and-resource-pipelines-interact) and resolved for this change request. |

The payload limit is 3 MB.

### Example: route approvals based on what changed

Because the pipeline receives both `before` and `after`, you can branch on the substance of a change rather than only on who submitted it. For example, a pipeline can:

* Notify a team, or require customer success approval, when a rule in `after` turns a feature on for a key customer
* Require a senior approver only when `after.trafficAllocation` is 100 in a production environment, and auto-approve smaller rollouts
* Require an approval step when a treatment is removed, by comparing the `treatments` arrays in `before` and `after`
* Skip approval entirely for a kill, by checking whether `isKilled` changed from `false` to `true`
* Route to different approver groups based on `environment.name` or `resourceType`
* Look up an external system using a value in `properties`, such as verifying that `jiraTicket` refers to an open ticket before allowing the change

Use [conditional execution](https://developer.harness.io/continuous-delivery/use-continuous-delivery/cd-building-blocks/executions/step-and-stage-conditional-execution-settings.md) and [Approval steps](https://developer.harness.io/harness-platform/use-harness-platform/approvals/approvals-tutorial.md) in the gating pipeline to express this logic.

## View pipeline executions for a flag or segment

Each environment on a feature flag has its own set of tabs: **Definition**, **Metrics Impact**, **Monitoring**, **Live Tail**, **Audit logs**, **Integrations**, and **Pipeline Executions**.

The **Pipeline Executions** tab lists the pipeline runs triggered by change requests for that feature flag or segment in that environment, so you can see how a given change was gated without leaving the resource.

![](https://1473625385-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FrT2RGHAjtBTaObzchfpb%2Fuploads%2Fgit-blob-d16769fd4deef423a0ca58b0a13bb260e07fcc98%2Fpipeline-gate-executions-tab.png?alt=media)

Each entry is headed by the name of the pipeline that ran. Click the pipeline name to open it in Pipeline Studio. The entry reports the following:

| Field            | Description                                                                |
| ---------------- | -------------------------------------------------------------------------- |
| **Execution ID** | Identifier of the pipeline execution. Click the ID to open that execution. |
| **Triggered**    | When the change request started the pipeline.                              |
| **Completed**    | When the pipeline execution finished.                                      |
| **Result**       | The outcome of the pipeline execution, either `Succeeded` or `Failed`.     |

Below the result, the entry shows the resulting status of the change request, either **Published** or **Rejected**, followed by a **View change request** link.

A change request is applied to the definition only when the gating pipeline succeeds, in which case the change is published. If the pipeline fails, the change request is rejected and the definition is left unchanged.

### Review a gated change request

The **View change request** link opens a **Change summary** panel for the change request.

![](https://1473625385-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FrT2RGHAjtBTaObzchfpb%2Fuploads%2Fgit-blob-c7b5427cddeaa0599d53081fd35eb7d48101e8da%2Fpipeline-gate-change-summary.png?alt=media)

The panel reports:

* **Status**, along with who set it and when
* The **Feature flag** or **segment**, plus the **Environment**, **Version**, and **ID** the change applies to
* **Change Diff**, summarizing how many values the change adds and removes. Expand it to see the full diff.
* **Title**, if the submitter supplied one
* **Pipeline Execution**, listing the **Pipeline**, **Execution ID**, **Started** and **Finished** times, and **Duration**. The pipeline and execution ID are both links.
* **Properties**, showing the resolved value of each [property](#pass-properties-to-the-pipeline) passed to the pipeline
* **Proposed status update**, the rollout status the flag would move to, and **When is this change going to take effect**

This gives you the pipeline run and the change it was gating side by side, so you can trace a decision back to the specific definition change and property values that produced it.

### Trace a decision in the pipeline

Opening the execution shows which step decided the outcome. In the following example, the `Initialize` and `Step 1` steps succeeded and the `Approval` step was rejected, which rejected the change request.

![](https://1473625385-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FrT2RGHAjtBTaObzchfpb%2Fuploads%2Fgit-blob-5d8eb1f4dffe83449759a87c1e0ae87515c0b34c%2Fpipeline-gate-execution-detail.png?alt=media)

Selecting the **Approval** step shows the approver user groups, the approver who acted, and any comment they left, which is the audit trail for why a gated change was not published.

## Related documentation

The following pages cover related topics:

* [Environments](https://developer.harness.io/feature-management-experimentation/management-and-administration/environments.md)
* [Pipelines](https://developer.harness.io/feature-management-experimentation/management-and-administration/pipelines.md)
* [Approval flows](https://developer.harness.io/feature-management-experimentation/use-fme/feature-management/setup/approval-flows.md)
* [Policies](https://developer.harness.io/feature-management-experimentation/management-and-administration/policies.md)

{% @harness-feedback/feedback %}
