> 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/harness-platform/use-harness-platform/pipelines/add-a-stage.md).

# Add a stage

Stages are the primary building blocks of a Harness pipeline. A stage defines what work the pipeline performs and on what infrastructure that work runs. You can add stages of different types depending on the modules you have enabled in your project. This topic explains how to add and configure stages, including standard stages, custom stages, and dynamic stages.

This functionality is limited to the modules and settings that you have access to.

### What you will learn from this topic <a href="#what-you-will-learn-from-this-topic" id="what-you-will-learn-from-this-topic"></a>

* How to add a [stage](#add-a-stage) to your pipeline
* How to configure [stage names](#stage-names) and identifiers
* How to use [stage variables](#stage-variables) to pass data
* How to configure [advanced stage settings](#advanced-stage-settings) such as conditional executions and failure strategies
* How to add a [custom stage](#add-a-custom-stage) for use cases outside standard stage types
* How to add a [dynamic stage](#add-a-dynamic-stage) to execute generated pipeline YAML

***

### Before you begin <a href="#before-you-begin" id="before-you-begin"></a>

* **Harness project access:** Ensure you have View and Create/Edit permissions on [Pipelines](/harness-platform/use-harness-platform/platform-access-control/permissions-reference.md#pipelines). An administrator must assign you a role that includes these permissions. For more information, refer to [RBAC in Harness](/harness-platform/3.0/harness-platform-resources/platform-access-control/rbac-in-harness.md).
* **Module enablement:** The available stage types depend on which Harness modules are enabled in your project. For more information, refer to [Create organizations and projects](/harness-platform/new-to-harness-platform/get-started.md#create-an-organization).

***

### Add a stage <a href="#add-a-stage" id="add-a-stage"></a>

Perform the following steps to add a stage to a pipeline:

1. Navigate to your Harness project and create a pipeline in any module that supports pipelines.
2. In your pipeline, select **Add Stage**, and then select the stage type.

   The following stage types are available:

   * **Deploy:** Deploy services, serverless functions, or other workloads.
   * **Build:** Build, test, and push artifacts to repositories.
   * **Approval:** Approve or reject changes during pipeline progress.
   * **Feature Flag:** Enable or disable functionality remotely without redeploying code.
   * **Pipeline:** Run a pipeline as a stage in another pipeline.
   * **Custom Stage:** [Custom stages](#add-a-custom-stage) are flexible stages you can configure for use cases outside the standard stage types.
   * **Infrastructure**: Provision, configure, and manage infrastructure resources as part of the pipeline.
   * **Dynamic Stage:** [Dynamic Stage](#add-a-dynamic-stage) allows you to import pipeline YAMLs within a stage. These YAMLs can either be generated and transformed at runtime or be directly passed to the input source field of the dynamic stage in encoded form.
   * **Developer Portal**: Integrate with your developer portal to automate and manage developer workflows within the pipeline.

   <figure><img src="/files/2u0IJ9Pwi06eme8LhpUW" alt="Stage type selection dialog showing all available stage types"><figcaption></figcaption></figure>

   <div data-gb-custom-block data-tag="hint" data-style="info" class="hint hint-info"><p>If a specific module or stage type is not shown, make sure the module is enabled in your project. For more information, refer to <a href="/pages/37ugEyqUtAoznhMiVOSk#create-an-organization">Create organizations and projects</a>.</p></div>
3. **Configure the stage settings.**

   You must provide a few initial settings, such as the **Stage Name**, to add a stage to a pipeline.

   After adding the stage, you can configure additional settings across the available tabs, such as [Stage Variables](#stage-variables), [Environment](/continuous-delivery/use-continuous-delivery/cd-building-blocks/environments/environment-overview.md), [Infrastructure](https://github.com/iKettles/harness-gitbook/tree/main/docs/continuous-delivery/x-platform-cd-features/environments/infrastructure-definitions/README.md), and other stage-specific options.

   The available settings depend on the module and stage type. For more information about the stage settings available for that module, refer to your module's documentation.
4. **Configure the stage execution.**

   If applicable to the stage type or module, use the **Execution** tab to add and configure the steps that define the tasks performed by the stage.

   You can also configure execution-related settings, such as [Execution Strategy](/continuous-delivery/use-continuous-delivery/manage-deployments/deployment-concepts.md), [Conditional Execution](/harness-platform/use-harness-platform/pipelines/step-skip-condition-settings.md), [Looping Strategy](/harness-platform/use-harness-platform/pipelines/looping-strategies/looping-strategies-matrix-repeat-and-parallelism.md), and [Failure Strategy](/harness-platform/use-harness-platform/pipelines/failure-handling/define-a-failure-strategy-on-stages-and-steps.md). The available steps and settings depend on the stage type. For details about configuring the available execution options, refer to your module's documentation.

***

#### Stage names <a href="#stage-names" id="stage-names"></a>

When you create a stage, you give it a name. Harness automatically creates an **Id** ([Entity Identifier](/harness-platform/use-harness-platform/references/entity-identifier-reference.md)) based on the name.

You can change the **Id** during initial stage creation. However, once the stage is saved, the **Id** becomes immutable.

You can change the **Name** at any time, but you cannot change the **Id**.

***

#### Stage variables <a href="#stage-variables" id="stage-variables"></a>

Stage variables are variables defined at the stage level and used to configure or reference values within the stage and in subsequent stages of the pipeline.

You can add stage variables in the Pipeline Studio's Visual Editor or YAML Editor.

{% tabs %}
{% tab title="Visual" %}
To add stage variables, go to a stage's **Overview** tab, expand the **Advanced** section, and then select **Add Variable**.

<figure><img src="/files/97ZoOG85eSGRgricDlgl" alt="Overview tab showing the Add Variable button in the Advanced section"><figcaption></figcaption></figure>
{% endtab %}

{% tab title="YAML" %}

```yaml
- stage:
    ...
    variables:
      - name: VAR_NAME
        type: String ## String or Secret
        description: ""
        value: 90
```

{% endtab %}
{% endtabs %}

Variable values can be [fixed values, runtime inputs, or expressions](/harness-platform/use-harness-platform/variables-and-expressions/runtime-inputs.md).

Stage variables are available across the pipeline and you can override their values in later stages.

* To reference stage variables in the same stage where they are defined, use the expression `<+stage.variables.VAR_NAME>`.
* To reference stage variables in other stages, use the expression `<+pipeline.stages.STAGE_ID.variables.VAR_NAME>`.
* You can also reference stage variables in files fetched at runtime. For example, create a stage variable called `NAME` and then reference it in the Kubernetes `values.yaml` file used by that stage by calling the [Harness expression](/harness-platform/use-harness-platform/variables-and-expressions/harness-variables.md) `<+stage.variables.NAME>`.

  ```yaml
  name: <+stage.variables.NAME>  
  replicas: 2  

  image: <+primary.artifact.image>  
  ...
  ```

  When you run this pipeline, the value you set for `NAME` in the stage settings is supplied to the `values.yaml` file.

***

#### Advanced stage settings <a href="#advanced-stage-settings" id="advanced-stage-settings"></a>

On the **Advanced** tab, you can configure:

* **Manual Execution**: Allows you to pause the pipeline at a stage and require a user to manually trigger the stage before it can continue. You can also configure a timeout; if the stage is not manually triggered within the specified time, the stage fails. For more information, refer to [Run a pipeline](/harness-platform/use-harness-platform/pipelines/pipeline-manual-run.md).
  * **Timeout**: Specifies the maximum amount of time Harness waits for the stage to complete. For manual stages, the timeout also determines how long the stage can remain waiting for manual execution before it fails.
* **Delegate Selector (optional)**: Allows you to specify which Harness Delegate should execute the stage or its associated tasks. Delegate selectors use delegate tags to target delegates with the required connectivity or capabilities. Stage-level delegate selectors can also be overridden by selectors configured at the step or step-group level. For more information, refer to [Select delegates with selectors](/harness-platform/use-harness-platform/delegates/delegate/manage-delegates/select-delegates-with-selectors.md).
* [Conditional executions](/harness-platform/use-harness-platform/pipelines/step-skip-condition-settings.md): Control when a stage executes based on conditions you define.
* [Failure strategies](/harness-platform/use-harness-platform/pipelines/failure-handling/define-a-failure-strategy-on-stages-and-steps.md): Define how the pipeline responds when a stage fails.
* [Looping strategies](/harness-platform/use-harness-platform/pipelines/looping-strategies/looping-strategies-matrix-repeat-and-parallelism.md): Run stages multiple times using matrix, repeat, or parallelism strategies.
* **Send Status to Git**: Allows Harness to send the stage's execution status to the Git provider for pipelines triggered by Git events, such as pull requests. This can be used to display the stage as a status check on the pull request and, where supported, customize the status check name. For more information, refer to [Git Experience](/harness-platform/use-harness-platform/git-experience/git-experience-overview.md).
  * **Name**: Specifies the name displayed for the stage's status check in the Git provider. You can use a fixed value or a [Harness expression](/harness-platform/use-harness-platform/variables-and-expressions/harness-variables.md) to generate the name dynamically.

***

### Add a custom stage <a href="#add-a-custom-stage" id="add-a-custom-stage"></a>

{% hint style="warning" %}
Custom stage executions will count towards service license consumption. Harness CD will consume 1 Service license for every 2000 custom stage executions. For more information, refer to [licensing for pipelines with no service](/continuous-delivery/troubleshooting-and-resources/resources/service-licensing-for-cd.md#pipelines-with-no-service).
{% endhint %}

Harness provides predefined stages for common pipeline operations, including [Build (CI)](/continuous-integration/readme.md), [Deploy (CD)](/continuous-delivery/readme.md), and [Approval](/harness-platform/use-harness-platform/approvals/adding-harness-approval-stages.md) stages. Each stage type provides settings and steps specific to its intended use case.

Use a **Custom** stage when you need to perform operations that do not require the predefined settings or functionality of the standard stage types. For example, you can use a Custom stage for ad hoc provisioning or to run jobs before or after a deployment stage. Unlike Build, Deploy, or Approval stages, a Custom stage has no predefined functionality or requirements and provides flexibility for use cases outside the standard stages.

Perform the following steps to add a Custom stage to your pipeline:

1. Select **Add Stage** in the pipeline.
2. Select **Custom** as the stage type.

   <figure><img src="/files/Xpt9oXNe75D2RrFsyJHy" alt="Custom stage option in stage type selection"><figcaption></figcaption></figure>
3. Enter a name for the stage and configure the required settings.
4. Add the required steps in the **Execution** tab.
5. Configure optional settings, such as **Stage Variables**, **Environment**, **Infrastructure**, and **Advanced** settings.
6. Save the stage.

#### Environments and infrastructure definitions in custom stages <a href="#environments-and-infrastructure-definitions-in-custom-stages" id="environments-and-infrastructure-definitions-in-custom-stages"></a>

You can also use **Environment** and **Infrastructure Definition** in Custom stages.

* **Service** is not supported in Custom stages.
* Both **Environment** and **Infrastructure Definition** are optional. You can have a Custom stage with no **Environment** or **Infrastructure Definition** or with only **Environment** or with both **Environment** and **Infrastructure Definition**.
* Currently, you can only use a single environment and single infrastructure.
* Harness does not support environment propagation in the Custom stage.
* Harness does not support dynamic infrastructure provisioning in the Custom stage.
* Harness does not support environment and infrastructure filtering in the Custom stage.
* You can add both environment global and infrastructure global overrides in Custom stages.
* Service-specific overrides are not supported as services are not supported in Custom stages.

#### Custom stage capabilities <a href="#custom-stage-capabilities" id="custom-stage-capabilities"></a>

Custom stages support the following capabilities:

* [Stage variables](#stage-variables).
* [Advanced stage settings](#advanced-stage-settings): Conditional executions, failure strategies, and looping strategies.
* [Templates](/harness-platform/use-harness-platform/templates/template.md): You can [create stage templates](/harness-platform/use-harness-platform/templates/add-a-stage-template.md) based on Custom stages, and you can use step templates in Custom stages. You can also create pipeline templates from pipelines that have Custom stages.
* [Delegate selectors](/harness-platform/use-harness-platform/delegates/delegate/manage-delegates/select-delegates-with-selectors.md): You can select the [Harness Delegate](/harness-platform/use-harness-platform/delegates/delegate/delegate-concepts/delegate-overview.md) to use for each step in a Custom stage. If you do not specify a delegate, Harness uses the default delegate selection process.

{% hint style="info" %}
**ROLLBACK**

Custom stages do not support [rollback failure strategies](/harness-platform/use-harness-platform/pipelines/failure-handling/define-a-failure-strategy-for-pipelines.md), but you can use [conditional executions](/harness-platform/use-harness-platform/pipelines/step-skip-condition-settings.md) to run steps or stages based on the outcomes of other steps or stages. For example, run a step only if a previous step succeeded.
{% endhint %}

#### Steps in custom stages <a href="#steps-in-custom-stages" id="steps-in-custom-stages"></a>

* The Custom stage leverages steps from other stage types. Any steps listed in the Step Library for your Custom stages are also available for Build, Deploy, or Approval stages. Harness has no steps that are applicable only to the Custom stage.
* The Custom stage cannot use module-specific steps. Steps specific to CI and CD stages, like the Rolling Deployment step, are not available for the Custom stage.
* Licensing is applied to steps in Custom stages. For example, CD steps, such as the HTTP step, are available for the Custom stage only if you have a CD license.

{% hint style="info" %}
Delegate-based steps, such as shell scripts and command steps, can run for a maximum of 4 days. This applies to any tasks executed via the Harness Delegate. Ensure that your workflows account for this runtime, as any delegate-based step exceeding 4 days will not complete successfully.
{% endhint %}

***

### Add a dynamic stage <a href="#add-a-dynamic-stage" id="add-a-dynamic-stage"></a>

A **Dynamic Stage** is a Harness pipeline feature that allows you to import and execute pipeline YAML within a stage. It is similar to running an entire pipeline within a stage. The pipeline YAML can be generated or transformed at runtime by a previous stage, or provided directly to the Dynamic Stage's source input in encoded form. Dynamic Stages work across Harness CI and CD modules.

{% hint style="info" %}
Dynamic Stage is behind the Feature Flag `PIPE_DYNAMIC_STAGE_EXECUTION`. Contact [Harness Support](mailto:support@harness.io) to enable this stage.
{% endhint %}

Perform the following steps to add a Dynamic Stage to your pipeline:

1. Select **Add Stage** in the pipeline.
2. Select **Dynamic Stage** as the stage type.

   <figure><img src="/files/Ut4vlfubjpyZKq5VFZpF" alt="Dynamic Stage option in stage type selection"><figcaption></figcaption></figure>
3. Enter the **Stage Name** and click **Set Up Stage**.
4. In the **Overview** tab, select **Source Location**:
   * [Inline](#define-inline-source-location): Provide the pipeline YAML directly in the Dynamic Stage.
   * [Remote](#define-remote-source-location): Load the pipeline YAML from a Git repository.
5. Configure execution-related settings, such as [Execution Strategy](/continuous-delivery/use-continuous-delivery/manage-deployments/deployment-concepts.md), [Conditional Execution](/harness-platform/use-harness-platform/pipelines/step-skip-condition-settings.md), [Looping Strategy](/harness-platform/use-harness-platform/pipelines/looping-strategies/looping-strategies-matrix-repeat-and-parallelism.md), and [Failure Strategy](/harness-platform/use-harness-platform/pipelines/failure-handling/define-a-failure-strategy-on-stages-and-steps.md) in the **Advanced** tab, if required.
6. Save the pipeline.

#### Define inline source location <a href="#define-inline-source-location" id="define-inline-source-location"></a>

Define the inline source to provide pipeline YAML to the Dynamic Stage using the following two methods:

Upon execution, the Dynamic Stage executes the stages and steps as per the Dynamic Stage Source YAML. You can click on the **View Source** option to view the decoded pipeline YAML.

<figure><img src="/files/MNrqizuo6FrKcgtQZPKO" alt="Dynamic Stage execution showing View Source option"><figcaption></figcaption></figure>

**Encoded YAML using Expressions**

Dynamic Stage accepts Expressions in the source input field, which enables the execution of YAML pipelines generated at runtime. To achieve this, you can use an expression to output the YAML pipeline in base64-encoded form, for example, through a previous stage or step that outputs the pipeline YAML in base64-encoded form through an output variable.

The following example demonstrates a pipeline in which a Drone pipeline is converted into a Harness pipeline through a plugin, and the encoded Harness pipeline YAML is passed to the Dynamic Stage through an expression containing the output variable belonging to the stage prior to the Dynamic Stage. This output variable stores the encoded pipeline YAML and, hence, serves as the source for the Dynamic Stage.

<figure><img src="/files/wZOXTon4HD3CbOEFFhWx" alt="Pipeline showing Dynamic Stage receiving encoded YAML from previous stage"><figcaption></figcaption></figure>

**Encoded YAML via Fixed Value**

Dynamic Stage accepts the encoded value of the pipeline YAML in the source input field. You can convert any Harness Pipeline YAML into base64-encoded form and pass it to the Dynamic Stage.

The example below demonstrates a pipeline consisting of a Dynamic Stage where the encoded Pipeline YAML is being provided to the source as a Fixed Value.

<figure><img src="/files/srVsFNut9FozK6vSSlCx" alt="Dynamic Stage configuration with fixed value encoded YAML"><figcaption></figcaption></figure>

#### Define remote source location <a href="#define-remote-source-location" id="define-remote-source-location"></a>

Load the pipeline YAML from a Git repository.

* **Git Connector:** Select the connector used to access the Git repository.
* **Repository:** Select or enter the name of the Git repository containing the pipeline YAML.
* **Branch Name:** Select or enter the branch containing the pipeline YAML.
* **File Path:** Specify the path to the pipeline YAML file in the repository.
* **Commit ID:** Optionally specify the commit from which to retrieve the pipeline YAML.

<figure><img src="/files/E6xX45zh0320LtyNbXUR" alt="Dynamic Stage configuration with remote git encoded"><figcaption></figcaption></figure>

***

### Next steps <a href="#next-steps" id="next-steps"></a>

* [Organize steps in step groups](/harness-platform/use-harness-platform/pipelines/use-step-groups.md): Group and organize steps within a stage for better organization.
* [Pipeline chaining in Harness](/harness-platform/use-harness-platform/pipelines/pipeline-chaining.md): Chain pipelines together to create complex workflows.
* [Define failure strategies](/harness-platform/use-harness-platform/pipelines/failure-handling/define-a-failure-strategy-on-stages-and-steps.md): Configure how stages handle failures.