> 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/continuous-delivery/3.0/use-deployments/helm/overview.md).

# Overview

A Helm stage lets you deploy applications packaged as Helm charts to any Kubernetes cluster. You configure a Native Helm service with your chart and values, point it at a Helm infrastructure definition, choose a deployment strategy, and Harness manages the full Helm release lifecycle: install, upgrade, and rollback.

***

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

* A Kubernetes cluster with outbound HTTPS access to `app.harness.io`.
* A delegate running in the cluster. Go to [Getting Started](/continuous-delivery/3.0/new-to-deployments/get-started.md#step-1-install-a-delegate) to install one.
* A Helm chart in a Git repository, Helm repository, OCI registry, S3, or GCS.

***

### Set up a Helm deployment <a href="#set-up-a-helm-deployment" id="set-up-a-helm-deployment"></a>

When you create a pipeline, Harness adds a default **Stage 1** automatically. You can edit it and add a deployment target, service, and environment, but editing an existing stage does **not** give you the execution strategy wizard and you have to add steps manually.

To get the strategy wizard, create a new stage:

1. Go to **Pipelines** and select **Create Pipeline**. Enter a name, select **Inline** or a Git store, and select **Create**.
2. Delete the default **Stage 1**, then select **+** to add a new stage.
3. Select **Deploy** and select **Next**.
4. Enter a stage name and set **Deployment Target** to **Native Helm**. Select **Next**.

The wizard then walks you through service, environment, and strategy. The sections below explain each piece.

***

### Service <a href="#service" id="service"></a>

A Helm service holds the chart source, values files, and service-level variables. The service deployment type is **Native Helm**. Services are reusable — configure once and reference across multiple stages and pipelines. Stages can override values files and variables per deployment without changing the shared service definition.

Go to [Helm services](/continuous-delivery/3.0/use-deployments/helm/helm-services.md) to configure chart sources and values overrides.

***

### Environment and infrastructure <a href="#environment-and-infrastructure" id="environment-and-infrastructure"></a>

An environment is a logical target (dev, staging, production). The **infrastructure definition** within the environment is a **Native Helm infrastructure** — it points to the Kubernetes cluster and namespace where Harness runs the Helm release. It references a Kubernetes connector, which uses a Delegate running inside your network to connect to the cluster.

Go to [Helm infrastructure](/continuous-delivery/3.0/use-deployments/helm/helm-infrastructure.md) to configure environments, infrastructure definitions, and connectors.

***

### Deployment strategies <a href="#deployment-strategies" id="deployment-strategies"></a>

| Strategy                            | What it does                                                                                                      |
| ----------------------------------- | ----------------------------------------------------------------------------------------------------------------- |
| **Helm Basic Deploy Strategy**      | Runs `helm upgrade --install` in a single phase. Suitable for most workloads.                                     |
| **Helm Canary Deploy Strategy**     | Deploys a canary release at a reduced instance count alongside the stable release, then promotes to full rollout. |
| **Helm Blue Green Deploy Strategy** | Brings up a full new Helm release, routes staging traffic to it, then swaps production traffic once validated.    |
| **Blank canvas**                    | No steps pre-populated. Build the execution sequence manually.                                                    |

Go to [Helm deployment strategies](/continuous-delivery/3.0/use-deployments/helm/helm-deployment-strategies/basic.md) to view step-by-step walkthroughs.

### Additional steps <a href="#additional-steps" id="additional-steps"></a>

The strategy wizard adds the minimum steps for the selected strategy. You can add further Helm steps to extend the stage.

| Step                                                                                                           | What it does                                               |
| -------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------- |
| [Helm Basic Deploy](/continuous-delivery/3.0/use-deployments/helm/step-library/helm-basic-deploy.md)           | Run `helm upgrade --install` as a standalone step          |
| [Helm Rollback](/continuous-delivery/3.0/use-deployments/helm/step-library/helm-rollback.md)                   | Roll back a Helm release to a previous revision            |
| [Helm Delete](/continuous-delivery/3.0/use-deployments/helm/step-library/helm-delete.md)                       | Delete a Helm release from the cluster                     |
| [Helm Canary Deploy](/continuous-delivery/3.0/use-deployments/helm/step-library/helm-canary-deploy.md)         | Deploy a canary release at a specified instance count      |
| [Helm Canary Delete](/continuous-delivery/3.0/use-deployments/helm/step-library/helm-canary-delete.md)         | Remove the canary release before promoting to full rollout |
| [Helm Blue Green Deploy](/continuous-delivery/3.0/use-deployments/helm/step-library/helm-blue-green-deploy.md) | Deploy the new release to the stage environment            |
| [Helm Blue Green Swap](/continuous-delivery/3.0/use-deployments/helm/step-library/helm-blue-green-swap.md)     | Swap traffic from the stage environment to production      |

***

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

Each stage has a set of settings accessible from the stage editor. A separate pipeline stages reference covers all of these in depth; the descriptions below give you enough to get started.

#### Clone <a href="#clone" id="clone"></a>

Controls whether the stage clones source code before running steps. Set to `false` to skip cloning (disabled by default).

```yaml
clone: false
```

#### Platform <a href="#platform" id="platform"></a>

Sets the operating system and CPU architecture for the stage execution environment.

| OS      | Supported architectures |
| ------- | ----------------------- |
| Linux   | AMD64, ARM64            |
| macOS   | ARM64 only              |
| Windows | AMD64 only              |

```yaml
platform:
  os: linux
  arch: amd64
```

#### Runtime <a href="#runtime" id="runtime"></a>

Defines where steps in the stage run. **The `runtime` block is mandatory for Helm deployments** — a stage without it cannot connect to a cluster and fails immediately.

**Kubernetes**: steps run as pods on a cluster you specify.

```yaml
runtime:
  kubernetes:
    namespace: <target-namespace>
    connector: <your-kubernetes-connector-id>
```

**Cloud**: steps run on Harness-hosted infrastructure.

```yaml
runtime:
  cloud: {}
```

**Shell**: steps run directly on the machine where the Delegate is installed.

```yaml
runtime:
  shell: {}
```

#### Shared paths <a href="#shared-paths" id="shared-paths"></a>

By default, all steps in a stage share the same workspace. Use `shared-paths` to make additional filesystem paths available across steps.

```yaml
shared-paths:
  - /shared/output
```

#### Strategy <a href="#strategy" id="strategy"></a>

Configures a looping strategy so the stage runs multiple times across a set of values or conditions.

**Matrix** — runs the stage for each combination of values in the matrix.

```yaml
strategy:
  matrix:
    environment: [dev, staging, prod]
  max-concurrency: 2
```

**For loop** — runs the stage a fixed number of times.

```yaml
strategy:
  for:
    iterations: 3
```

**While loop** — runs the stage until a condition is false or a max iteration count is reached.

```yaml
strategy:
  while:
    max-iterations: 10
    condition: "${{some.expression}}"
```

Add `fast-fail: true` to any strategy to stop remaining iterations immediately if one fails.

#### Concurrency <a href="#concurrency" id="concurrency"></a>

Limits how many instances of this stage can run simultaneously across pipeline executions.

#### On failure <a href="#on-failure" id="on-failure"></a>

Defines what Harness does when the stage fails. Common actions are `stage-rollback`, `retry`, `skip`, and `mark-as-success`.

```yaml
on-failure:
  errors: all
  action: stage-rollback
```

#### Conditional execution <a href="#conditional-execution" id="conditional-execution"></a>

Controls whether the stage runs based on an expression evaluated at runtime.

```yaml
when:
  condition: "${{inputs.deploy_env == 'prod'}}"
```

#### Delegate <a href="#delegate" id="delegate"></a>

Pins the stage to a specific delegate by tag. By default Harness selects any available delegate.

```yaml
delegate: my-delegate-tag
```

#### Inputs and outputs <a href="#inputs-and-outputs" id="inputs-and-outputs"></a>

Declare typed inputs the stage accepts and outputs it produces. Inputs are available as `${{inputs.<name>}}` within the stage.

```yaml
inputs:
  target_env:
    type: environment
    description: Target deployment environment

outputs:
  release_id:
    type: string
```

#### Environment variables <a href="#environment-variables" id="environment-variables"></a>

Set environment variables available to all steps in the stage.

```yaml
env:
  APP_ENV: production
  LOG_LEVEL: info
```

#### Timeout duration <a href="#timeout-duration" id="timeout-duration"></a>

Maximum time the stage is allowed to run before Harness terminates it. Default is `24h`.

```yaml
timeout: 2h
```

#### Build intelligence and cache intelligence <a href="#build-intelligence-and-cache-intelligence" id="build-intelligence-and-cache-intelligence"></a>

**Build intelligence** skips steps whose outputs are unchanged, reducing execution time on repeated runs. **Cache intelligence** stores and restores dependency caches between runs to speed up build steps. These are primarily relevant for build stages; in stages without build steps they have no effect unless you include build steps.

***

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

* Go to [Helm services](/continuous-delivery/3.0/use-deployments/helm/helm-services.md) to configure chart sources, values files, and artifact sources
* Go to [Helm infrastructure](/continuous-delivery/3.0/use-deployments/helm/helm-infrastructure.md) to configure environments and infrastructure definitions
* Go to [Basic deployment](/continuous-delivery/3.0/use-deployments/helm/helm-deployment-strategies/basic.md) to walk through a single-phase Helm upgrade
* Go to [Canary deployment](/continuous-delivery/3.0/use-deployments/helm/helm-deployment-strategies/canary.md) to walk through a staged rollout with canary release
* Go to [Blue-green deployment](/continuous-delivery/3.0/use-deployments/helm/helm-deployment-strategies/blue-green.md) to walk through stage/production swap and rollback
* Go to [Step reference](/continuous-delivery/3.0/use-deployments/helm/step-library/helm-basic-deploy.md) to view all available Helm steps