Synchronize parallel stages and step groups using Barriers

Synchronize parallel stages and step groups in your Harness pipeline using barriers.

This topic describes how to synchronize stages and step groups in your pipeline using barriers.

Harness provides multiple options for controlling resource usage and protecting capacity limits. Go to controlling resource usage with Barriers, Resource Constraints, and Queue steps to compare barriers, resource constraints, and queue steps.

What you will learn from this topic

• How barriers work to synchronize parallel execution

• How barrier scope determines where barriers can be used

• How barrier failure behavior affects pipeline execution

• How to use barriers and looping strategies together

• How to add a barrier to your pipeline

• How to use a barrier in a step within stages

• How to use multiple barriers in a stage or step group for different synchronization points

• How to avoid rollback barrier cycles that cause deadlocks

• When to use barriers versus other flow-control options

---

Before you begin

• Harness project access: You need View and Edit permissions on Pipelines. An administrator must assign you a role that includes these permissions. For more information, refer to RBAC in Harness.

• Existing pipeline: You need a pipeline with parallel stages or step groups to use barriers. For more information, refer to Add a stage.

---

How barriers work

Barriers follow these rules:

• A barrier synchronizes two or more stages or step groups that use the same Barrier Reference and can execute concurrently.

• All participating stages or step groups must reach the barrier before any of them can proceed.

• If a participating stage or step group fails before reaching the barrier, the other participants are signaled to fail.

• If a participant does not reach the barrier before the timeout, the barrier fails.

• Each affected stage or step group follows its configured failure strategy.

Barrier steps are only supported inside Deploy and Custom stage types.

Barriers are scoped to a single pipeline by default. Barriers can also synchronize stages across parent and child pipelines when the PIPE_BARRIERS_FOR_CHAINED_PIPELINES feature flag is enabled. Contact Harness Support to enable the feature.

Barrier scope

Barriers are scoped to a pipeline. The same barrier reference can be used by multiple stages or step groups within the same pipeline to synchronize execution. A barrier reference cannot normally be used across separate pipelines. For example, a barrier created in one pipeline cannot be referenced by a stage in another pipeline.

Barriers can also be used across parent and child pipelines when the feature for chained pipelines is enabled. For more information, refer to Pipeline chaining in Harness.

This is especially useful because your pipelines can coordinate execution flows both within a single pipeline and across pipeline hierarchies.

Barrier synchronization requirements

A barrier only synchronizes execution when the related stages or step groups can reach the barrier concurrently.

Do not use the same Barrier Reference in sequential stages or step groups. The first stage or step group waits at the barrier for a later one, but the later one cannot start until the first stage completes. The barrier then fails once its timeout expires.

Barrier failure behavior

If a stage or step group fails before reaching a shared barrier, the other stages or step groups waiting at the barrier are also signaled to fail. Each affected stage or step group follows its configured failure strategy.

If a stage or step group does not reach the barrier before the barrier timeout expires, the barrier is considered failed and execution fails according to the configured failure strategy.

---

When to use barriers

Use barriers when you need to synchronize execution at parallel stages or step groups at a specific point in a pipeline.

For example, if multiple services are deployed in parallel and a verification step should run only after all deployments reach a specific point, use a barrier to synchronize them.

Use other flow-control options for different requirements:

• Barriers: Synchronize parallel stages or step groups within a pipeline.

• Resource Constraints: Prevent simultaneous deployments to the same service or infrastructure combination.

• Queue steps: Control the execution order of pipeline executions that share a resource key.

---

Barrier synchronization example

Here is a visualization of how barriers synchronize parallel stages:

• Stage A and Stage B both wait at Barrier X and proceed only when both reach it.

• Stage B and Stage C both wait at Barrier Y and proceed together once both are ready.

This allows you to control complex coordination logic within a pipeline without resorting to manual delays or checks.

---

Add a barrier

A barrier is a name added in a pipeline's Flow Control settings.

Perform the following steps to add a barrier:

1. In your pipeline, select Flow Control.

2. In Flow Control, select Add Barrier.

3. In Barrier Name, enter a unique name, and then click outside of the settings. The barrier is created.

Next, select the name using the Barrier step in the stages where you want to synchronize.

---

Use a barrier in a step

Perform the following steps to apply a barrier:

1. In your stage, under Execution, select Add Step, and then select Barrier.

2. Enter a name for the step.

3. In Timeout, enter the timeout period in milliseconds. For example, 600000 milliseconds is 10 minutes. The timeout period determines how long each stage with a barrier must wait for the other stages to reach the barrier point. When the timeout expires, it is considered a deployment failure.

4. Barrier timeouts are not hard timeouts. A barrier can fail anytime between the timeout value and timeout + 1 minute.

5. In Barrier Reference, select the name of an existing barrier.

6. Select Apply Changes.

---

Use multiple barriers in a stage or step group

You can add multiple Barrier steps to the same stage or step group. Each Barrier step in the same stage or step group must use a different Barrier Reference.

For example, a stage can use one barrier to synchronize deployment steps and another barrier to synchronize verification steps later in the same stage.

Use the same Barrier Reference across different parallel stages or step groups that should synchronize at a particular point.

---

Barriers and looping strategies

Barriers are supported in all looping strategies. You can use them when repeating stages, looping, or in matrices, or when using multi-service or multi-environment stages.

Keep the following in mind when you use barriers with a looping strategy:

• Use the same Barrier Reference for all looped stages or step groups that need to synchronize, so that all of them execute up to the Barrier step and then continue or fail together.

• When a looping strategy that contains a barrier also sets maxConcurrency, Harness limits the barrier to the number of iterations that actually run concurrently, so the barrier only waits on the iterations that are running. This prevents the deadlock that would otherwise occur if the barrier waited on iterations that are still queued behind the concurrency limit.

• For multi-service deployments, enable Deploy Services in Parallel so all participating stages can reach the barrier, instead of the pipeline waiting for one stage to complete before starting the next.

• A barrier can synchronize multiple groups of looped stages, or a single stage group with looped stages, as long as the participating executions use the same Barrier Reference. This applies even if one group starts later than another.

• Barriers are also supported across child pipelines. A parent pipeline can define and use a barrier, and any child pipeline can reference and synchronize using the same barrier.

---

Avoid rollback barrier cycles

Do not reuse the same Barrier Reference in both the normal execution flow and a rollback section. A barrier waits for every position that shares its reference, including any position in a rollback section. Because rollback steps run only when the normal flow fails, that rollback position never arrives during a successful run. Following the barrier failure behavior described earlier, the barrier fails once its timeout expires, and the affected stages follow their configured failure strategy, even though the deployment itself completed successfully.

For example, if the reference wall3 is used in the normal steps of two parallel stages and also in the rollback steps of one stage, the two normal-flow positions reach the barrier and wait for the rollback position. The rollback position does not execute unless the stage fails, so the barrier eventually times out.

To synchronize a rollback flow, use a dedicated barrier reference for rollback instead of the one used in the normal flow.

Barrier reference cycle (anti-pattern) and the corrected configuration

# Anti-pattern: barrier "wall3" is referenced in both normal and rollback steps
pipeline:
  stages:
    - parallel:
        - stage:
            name: deploy
            spec:
              execution:
                steps:
                  - step:
                      type: Barrier
                      spec:
                        barrierRef: wall3        # normal flow
                rollbackSteps:
                  - step:
                      type: Barrier
                      spec:
                        barrierRef: wall3        # rollback flow -> cycle
        - stage:
            name: deploy2
            spec:
              execution:
                steps:
                  - step:
                      type: Barrier
                      spec:
                        barrierRef: wall3        # normal flow
  flowControl:
    barriers:
      - identifier: wall3

# Corrected: use a dedicated reference for the rollback flow
  flowControl:
    barriers:
      - identifier: wall3            # normal flow
      - identifier: wall3_rollback   # rollback flow
# Set barrierRef: wall3_rollback in the rollback step so it no longer shares "wall3".

---

Next steps

You have synchronized parallel stages and step groups using barriers. Continue your learning journey with the following:

• Step groups: Group related steps and apply shared configuration across a stage.

• Controlling deployments with Barriers, Resource Constraints, and Queue steps: Compare the options for controlling resource usage and protecting capacity limits.

• Looping strategies: Repeat stages and steps using matrix, repeat, and parallelism.