YAML reference

Complete YAML reference for Harness v1 pipelines: every key, its type, and a minimal example.

This page is a flat reference for all YAML keys supported in Harness v1 pipelines. Keys are grouped by scope: pipeline root, stage, step, and execution controls. Each section shows the key, its type, whether it is required, and a verified example.

What you will learn

• The complete YAML structure for the pipeline root, stages, and steps

• How to configure clone, inputs, notifications, and execution controls in YAML

• The keys for strategies, failure handling, conditional execution, and timeout

• YAML syntax for run steps, group steps, and parallel step groups

---

Pipeline root

The root key is always pipeline:.

pipeline:
  id: my_pipeline
  name: My Pipeline
  description: Optional description
  clone:
    enabled: false
  inputs:
    env:
      type: string
      default: production
      desc: Target environment
      required: false
  delegate: my-delegate
  timeout: 2h
  allow-stage-executions: true
  fixed-inputs-on-rerun: false
  notifications:
    - on:
        - pipeline:
            - failed
      uses: slack
      with:
        url: https://hooks.slack.com/services/your-webhook
  stages: []

Key	Type	Required	Description
id	string	Yes	Unique identifier for the pipeline. Used in expressions.
name	string	Yes	Display name shown in the UI.
description	string	No	Free-text description.
clone	object	No	Controls source repository cloning. See Clone.
inputs	map	No	Typed runtime parameters. See Inputs.
delegate	string or list	No	Delegate name or tag list for routing execution.
timeout	duration	No	Maximum pipeline run time. Default: 24h.
allow-stage-executions	boolean	No	When true, allows selective stage execution at runtime.
fixed-inputs-on-rerun	boolean	No	When true, locks inputs to original values on rerun.
notifications	list	No	Notification rules for pipeline events. See Notifications.
stages	list	Yes	The ordered list of stages.

---

Clone

Controls whether and how Harness clones a source repository before running steps. The repo is cloned into /harness inside the runner.

clone:
  enabled: true
  repo: deployment-samples
  depth: 1

To skip cloning entirely (common for pipelines that do not need source code):

clone:
  enabled: false

Key	Type	Default	Description
enabled	boolean	true	Set to false to skip cloning.
repo	string	none	Harness Code repository name to clone.
depth	integer	full	Commit depth. 1 for a shallow clone (faster); omit for full history.

---

Inputs

Pipeline inputs are typed parameters collected at runtime.

inputs:
  env:
    type: string
    default: production
    desc: Target environment
    required: false
  version:
    type: string
    required: true

Reference inputs in steps and conditions using ${{ inputs.<name> }} (CEL) or <+inputs.<name>> (JEXL in if conditions).

Field	Type	Description
type	string	string, number, boolean, secret, environment, or duration
default	value	Value used when none is provided at runtime.
desc	string	Label shown in the run form.
required	boolean	Whether a value must be supplied before running.

In if conditions (JEXL context), wrap input references in single quotes to avoid identifier errors: "'<+inputs.env>' == 'production'".

---

Notifications

notifications:
  - on:
      - pipeline:
          - start
          - failed
    uses: email
    with:
      recipients:
        - [e-mail]

  - on:
      - stage:
          - failed
    uses: slack
    with:
      url: https://hooks.slack.com/services/your-webhook

Events

Event	YAML value
Pipeline starts	pipeline: start
Pipeline succeeds	pipeline: success
Pipeline fails	pipeline: failed
Pipeline ends (any)	pipeline: end
Stage starts	stage: start
Stage succeeds	stage: success
Stage fails	stage: failed
Step fails	step: failed
Trigger fails	trigger: failed

Channels

Channel	uses value	Required with fields
Email	email	recipients: [[e-mail]]
Slack	slack	url: <webhook-url>
PagerDuty	pager-duty	key: <integration-key>
Microsoft Teams	ms-teams	url: <incoming-webhook-url>
Webhook	webhook	url: <webhook-url>

---

Stages

Each entry in pipeline.stages is a stage.

stages:
  - name: build
    id: build
    timeout: 30m
    on-failure:
      - errors:
          - all
        action: fail
    if: <+OnPipelineSuccess>
    strategy:
      matrix:
        env:
          - staging
          - production
    steps: []

Key	Type	Required	Description
name	string	Yes	Display name.
id	string	Yes	Unique identifier within the pipeline. Used in expressions.
timeout	duration	No	Maximum stage run time. Default: 24h. Status on expiry: Expired.
on-failure	list	No	Failure rules. See On failure.
if	string	No	JEXL condition. Stage is skipped when it evaluates to false. See Conditional execution.
strategy	object	No	Looping strategy. See Strategy.
steps	list	Yes (for plain stages)	The steps to run inside the stage.
group	n/a	n/a	Not valid at the stage level. Groups exist at the step level.
parallel	object	No	Parallel stage group. See Parallel stage group.
chain	object	No	Chained pipeline. See Chained pipeline.

Parallel stage group

Runs multiple child stages simultaneously.

stages:
  - name: parallel-group
    id: parallel_group
    parallel:
      stages:
        - name: branch-a
          id: branch_a
          steps:
            - name: step-a
              id: step_a
              run:
                script: echo "branch A"
        - name: branch-b
          id: branch_b
          steps:
            - name: step-b
              id: step_b
              run:
                script: echo "branch B"

Chained pipeline

Runs another pipeline as a stage.

stages:
  - name: deploy
    id: deploy
    chain:
      uses: my-org/my-project/child_pipeline
      with:
        inputs:
          env: production
        outputs:
          - name: image_tag
            value: ${{ stages.run.outputs.image_tag }}

Key	Type	Description
chain.uses	string	Child pipeline reference: org/project/pipeline_id.
chain.with.inputs	map	Input values to pass to the child pipeline.
chain.with.outputs	list	Output mappings to read from the child pipeline.

---

Steps

Each entry in stage.steps is a step. Steps run sequentially by default.

steps:
  - name: my-step
    id: my_step
    timeout: 10m
    on-failure:
      - errors:
          - all
        action: ignore
    if: <+OnPipelineSuccess>
    strategy:
      for:
        iterations: 3
    run:
      script: echo "hello"

Key	Type	Required	Description
name	string	Yes	Display name.
id	string	Yes	Unique identifier within the stage.
timeout	duration	No	Maximum step run time. Default: 2h. Status on expiry: Expired.
on-failure	list	No	Failure rules. See On failure.
if	string	No	JEXL condition. Step is skipped when it evaluates to false.
strategy	object	No	Looping strategy. See Strategy.
run	object	No	Run step. Executes a shell script. See Run step.
group	object	No	Group step. Runs child steps sequentially. See Group step.
parallel	object	No	Parallel step group. Runs child steps simultaneously. See Parallel step group.

Run step

- name: compile
  id: compile
  run:
    script: |
      echo "building..."
      make build
    shell: sh

Key	Type	Required	Description
run.script	string	Yes	Shell commands to execute. Multi-line supported with |.
run.shell	string	No	Shell to use: sh, bash, powershell, pwsh, python. Default: sh.

Group step

Runs child steps sequentially inside a named container.

- name: setup
  id: setup
  group:
    steps:
      - name: install
        id: install
        run:
          script: npm install
      - name: build
        id: build
        run:
          script: npm run build

Key	Type	Required	Description
group.steps	list	Yes	Steps to run sequentially inside the group.

The group key supports all step-level advanced settings: timeout, on-failure, strategy, if.

Parallel step group

Runs child steps simultaneously.

- name: parallel-tasks
  id: parallel_tasks
  parallel:
    steps:
      - name: task-a
        id: task_a
        run:
          script: ./task-a.sh
      - name: task-b
        id: task_b
        run:
          script: ./task-b.sh

Key	Type	Required	Description
parallel.steps	list	Yes	Steps to run simultaneously.

The parallel key supports all step-level advanced settings: timeout, on-failure, strategy, if.

---

Execution controls

Strategy

Applies to stages and steps. Runs the stage or step multiple times.

strategy:
  max-parallel: 2     # max simultaneous instances (0 = unlimited)
  fail-fast: true     # cancel all on first failure
  for:
    iterations: 3

For loop: runs a fixed number of times in parallel.

strategy:
  for:
    iterations: 3

Expression	Resolves to
${{ strategy.iteration }}	Current iteration index (0-based)
${{ strategy.iterations }}	Total number of iterations

While loop: runs sequentially up to a maximum number of iterations.

strategy:
  while:
    iterations: 5

Matrix: fans out across all combinations of the defined axes.

strategy:
  max-parallel: 2
  matrix:
    region:
      - us-east-1
      - eu-west-1
    env:
      - staging
      - production

Expression	Resolves to
${{ matrix.<axis> }}	Value of the axis for this instance
${{ strategy.iteration }}	Instance index (0-based)

Stage naming for matrix:

• Single axis: <id>_0, <id>_1, …

• Multiple axes: <id>_0_0, <id>_0_1, …

• With node-name: <id>_<node-name-value> (hyphens converted to underscores)

---

On failure

Controls what Harness does when a stage or step fails. Always a list.

on-failure:
  - errors:
      - all
    action: fail

Error types

Value	Description
all	Matches any failure
timeout	Step or stage exceeded its timeout
authentication	Authentication failure
authorization	Authorization failure
connectivity	Network or connectivity failure
unknown	Unclassified error
verification	Verification step failure
approval-rejection	An approval step was rejected
delegate-provisioning	Delegate could not be provisioned
delegate-restart	Delegate restarted during execution
input-timeout	Manual intervention wait timed out
policy-evaluation	OPA policy evaluation failed
user-mark-fail	User manually marked the step as failed

Actions

Value	Description
fail	Mark as failed and stop the pipeline (default)
abort	Abort the entire pipeline
ignore	Continue execution; pipeline shows IgnoreFailed status
success	Treat the failure as success
retry	Retry with backoff. See below.
manual-intervention	Pause for user action. See below.
stage-rollback	Roll back the current stage
pipeline-rollback	Roll back the entire pipeline

Retry with backoff

on-failure:
  - errors:
      - all
    action:
      retry:
        attempts: 3
        interval: 30s
        failure-action: fail

Retry then manual intervention

on-failure:
  - errors:
      - all
    action:
      retry:
        attempts: 2
        interval: 15m
        failure-action:
          manual-intervention:
            timeout: 20m
            timeout-action: fail

timeout-action valid values: fail, ignore, abort, success, stage-rollback, pipeline-rollback.

When manual-intervention is triggered, Harness pauses execution and displays a popup with options: Mark as Success, Ignore, Retry, Abort, Rollback Stage.

---

Conditional execution

The if key takes a JEXL expression that is evaluated at runtime. The stage or step runs only when the expression evaluates to true.

Base conditions

Expression	When it runs
<+OnPipelineSuccess>	All prior stages succeeded
<+OnPipelineFailure>	One or more prior stages failed
<+Always>	Always runs regardless of prior stage status

if: <+OnPipelineSuccess>
if: <+OnPipelineFailure>
if: <+Always>

Combined expressions

if: <+OnPipelineSuccess> && false

Input variable comparison (quotes required)

if: "'<+inputs.env>' == 'production'"

Always wrap <+inputs.varName> in single quotes inside the expression. Without them, the resolved value is treated as a JEXL identifier (undefined variable) rather than a string literal, causing an expression evaluation error.

---

Timeout

Sets the maximum run time for a stage or step. Accepts duration strings.

timeout: 30m

Format	Example	Equivalent
Seconds	90s	1 min 30 sec
Minutes	30m	30 minutes
Hours	2h	2 hours
Days	1d	24 hours
Combined	1h 30m	1 hour 30 minutes

• Stage default: 24h. Step default: 2h.

• When a stage or step times out it is marked as Expired.

• Handle timeouts specifically with errors: [timeout] in on-failure.

---

Concurrency

Limits how many instances of a strategy run simultaneously within a single execution. Applies at the stage level alongside a strategy.

strategy:
  matrix:
    region:
      - us-east-1
      - eu-west-1
      - ap-southeast-1
      - ap-northeast-1
  max-parallel: 2

max-parallel: 0 means unlimited (all instances start at once). max-parallel: 1 forces serial execution.

---

Duration format reference

All timeout and interval fields accept the following formats:

Format	Example
Seconds	30s
Minutes	15m
Hours	2h
Days	1d
Combined	1h 30m

---

Next steps

• Go to Pipeline settings to configure inputs, delegate, notifications, and more.

• Go to Strategy to review looping strategy details and verified expressions.

• Go to On failure to review the full failure handling reference.

• Go to Conditional execution to review JEXL condition details.

• Go to Timeout to review timeout behavior and status codes.

• Go to Steps overview to review step types and advanced settings.