Skip to main content

YAML reference -- pipelines

This topic describes the YAML schema for a Pipeline.

It includes common examples of the major schema entries.

New to Harness YAML? See Harness YAML Quickstart.

Viewing the YAML Schema​

The Harness YAML schema is available at github.com/harness/harness-schema. This repository contains the schema definition for Harness pipeline configuration files, enabling users to define and customize their pipelines effortlessly. This repo provides steps on how to embed the YAML schema in Visual Studio Code and Sublime Text.

In addition to the YAML schema available at github.com/harness/harness-schema, you can use Chrome DevTools to view the schema.

  1. Open Chrome DevTools and select the Network tab.
  2. Select the yaml-schema item.
  3. Select the Preview tab.
  4. Find the definitions section.

Pipeline Studio YAML Editor​

The Harness Pipeline Studio has both a Visual Editor and a YAML Editor.

The best way to get started with Harness YAML is to create a pipeline in the Visual Editor and then switch to the YAML Editor. If you haven't created a pipeline yet, try a tutorial to get started with Harness.

The YAML editor validates YAML before allowing you to save it.

To learn how to use the YAML editor, go to the Harness YAML quickstart.

Autocomplete and Command Palette​

The YAML editor has an autocomplete feature that makes it very easy to see what entries are available.

The keyboard command for autocomplete is Ctrl + Space.

If an entry already has a value, the autocomplete will not show you other options. You need to delete the value and then enter Ctrl + Space.

The command palette keyboard command is F1.

The command palette displays the keyboard shortcuts for all commands.

Limitations​

The visual editor lets you create Connectors inline but the YAML editor does not. For the YAML editor you need the entity Id of the Connector first. Typically, the Id is entered as the value for the connectorRef key.

This is a minor limitation as once you have entered in the Id you can configure the rest of the settings in YAML using autocomplete.

For example, here is a Connector with the name GCP Example and Id GCP_Example. You can see the Id used in the YAML as connectorRef: GCP_Example:

ConnectorYAML
...
type: Gcr
spec:
  connectorRef: GCP_Example
  imagePath: library/bar
  registryHostname: gcr.io
  tag: <+input>
identifier: foo
...

Once you have entered the Id in connectorRef, you can use autocomplete to view the remaining settings:

Schema Overview​

Harness pipeline YAML lets you model your release process declaratively. Each pipeline entity, component, and setting has a YAML entry.

Entries​

Entries are standard YAML associative arrays using key: value.

Settings are not quoted.

Indentation​

Whitespace indentation is 4 spaces.

Conventions​

Pipeline syntax uses the following conventions:

  • Quotes indicate an empty string. Values do not need quotes. Once you enter a value and save the quotes are removed.
  • Entries are listed as key: keyword. The key is a data type that corresponds to a setting such as skipResourceVersioning. The keyword is a literal definition for the setting, like false or K8sManifest.
  • Brackets indicate an inline series branch (an array of the data type). For example variables: []. To edit, you delete the brackets, enter a new line, and enter a dash -. Now you can use autocomplete to see the available entries.
  • Curly braces indicate an array separated by new lines. For example, tags: {}. To enter the entries for this type, delete the curly braces, enter a new line, and then enter the key: value pairs. For example:
...  
tags:  
    docs: "CD"  
    yaml example: ""  
...
  • The block style indicator | turns every newline within the string into a literal newline and adds one line at the end. The - indicates removes newlines from the end. For example:
...  
script: |-  
    echo "hello"  
  
    echo <+pipeline.name>  
...

Pipeline​

A Pipeline can have an unlimited number of configurations. This section simply covers the basic YAML schema.

Schema​

This is the basic schema for a Pipeline:

pipeline:  
    name: ""  
    identifier: ""  
    projectIdentifier: ""  
    orgIdentifier: ""  
    tags: {}  
    stages:  
        - stage:  
    flowControl:  
    notificationRules:

The projectIdentifier and orgIdentifier must match existing Project and Org Ids.

From here you can add stages, Service, Infrastructure, and Execution. Harness will not allow you to save your Pipeline until these three components are set up.

Example​

Here is a very basic Pipeline that meets the minimum requirements and uses a Shell Script step:

pipeline:  
    name: YAML  
    identifier: YAML  
    projectIdentifier: CD_Examples  
    orgIdentifier: default  
    tags: {}  
    stages:  
        - stage:  
              name: Deploy  
              identifier: Deploy  
              description: ""  
              type: Deployment  
              spec:  
                  serviceConfig:  
                      serviceRef: nginx  
                      serviceDefinition:  
                          type: Kubernetes  
                          spec:  
                              variables: []  
                  infrastructure:  
                      environmentRef: helmchart  
                      infrastructureDefinition:  
                          type: KubernetesDirect  
                          spec:  
                              connectorRef: <+input>  
                              namespace: <+input>  
                              releaseName: release-<+INFRA_KEY>  
                      allowSimultaneousDeployments: false  
                  execution:  
                      steps:  
                          - step:  
                                type: ShellScript  
                                name: Echo  
                                identifier: Echo  
                                spec:  
                                    shell: Bash  
                                    onDelegate: true  
                                    source:  
                                        type: Inline  
                                        spec:  
                                            script: echo "hello"  
                                    environmentVariables: []  
                                    outputVariables: []  
                                    executionTarget: {}  
                                timeout: 10m  
                      rollbackSteps: []  
              tags: {}  
              failureStrategies:  
                  - onFailure:  
                        errors:  
                            - AllErrors  
                        action:  
                            type: StageRollback

See also:

Stage​

A Stage is a subset of a Pipeline that contains the logic to perform one major segment of the Pipeline process. Stages are based on the different milestones of your Pipeline, such as building, approving, and delivering.

Schema​

stages:  
    - stage:  
          name: ""  
          identifier: ""  
          description: ""  
          type: Deployment  
          spec:  
              serviceConfig:  
                  serviceRef: ""  
                  serviceDefinition:  
                      type: ""  
                      spec:  
                          variables: []  
              infrastructure:  
                  environmentRef: ""  
                  infrastructureDefinition:  
                      type: ""  
                      spec:  
                          connectorRef: ""  
                          namespace: ""  
                          releaseName: release-""  
                  allowSimultaneousDeployments: ""  
              execution:  
                  steps:  
                      - step:  
                            type: ""  
                            name: ""  
                            identifier: ""  
                            spec:  
                  rollbackSteps: []  
          tags: {}  
          failureStrategies:  
              - onFailure:  
                    errors:  
                        - AllErrors  
                    action:  
                        type: StageRollback

Rollback steps, failure strategies, and execution conditions are set at the end of the stage YAML.

...  
                  rollbackSteps: []  
          tags: {}  
          failureStrategies:  
              - onFailure:  
                    errors:  
                        - AllErrors  
                    action:  
                        type: StageRollback  
...

Example​

stages:  
    - stage:  
          name: Deploy  
          identifier: Deploy  
          description: ""  
          type: Deployment  
          spec:  
              serviceConfig:  
                  serviceRef: nginx  
                  serviceDefinition:  
                      type: Kubernetes  
                      spec:  
                          variables: []  
              infrastructure:  
                  environmentRef: helmchart  
                  infrastructureDefinition:  
                      type: KubernetesDirect  
                      spec:  
                          connectorRef: <+input>  
                          namespace: <+input>  
                          releaseName: release-<+INFRA_KEY>  
                  allowSimultaneousDeployments: false  
              execution:  
                  steps:  
                      - step:  
                            type: ShellScript  
                            name: Echo  
                            identifier: Echo  
                            spec:  
                                shell: Bash  
                                onDelegate: true  
                                source:  
                                    type: Inline  
                                    spec:  
                                        script: echo "hello"  
                                environmentVariables: []  
                                outputVariables: []  
                                executionTarget: {}  
                            timeout: 10m  
                  rollbackSteps: []  
          tags: {}  
          failureStrategies:  
              - onFailure:  
                    errors:  
                        - AllErrors  
                    action:  
                        type: StageRollback

See also:

Service​

A Service represents your microservices and other workloads logically.

A Service is a logical entity to be deployed, monitored, or changed independently.

When a Service is added to the stage in a Pipeline, you define its Service Definition. Service Definitions represent the real artifacts, manifests, and variables of a Service. They are the actual files and variable values.

Schema​

spec:  
    serviceConfig:  
        serviceRef: ""  
        serviceDefinition:  
            type: ""  
            spec:  
                variables: []

If you propagate a Service from a previous stage, the YAML indicated it this way:

spec:  
    serviceConfig:  
        useFromStage:  
            stage: ""

Example​

spec:  
    serviceConfig:  
        serviceRef: nginx  
        serviceDefinition:  
            type: Kubernetes  
            spec:  
                variables: []

See also:

Infrastructure​

Infrastructure is defined under Environments. Environments represent your deployment targets logically (QA, Prod, etc). You can add the same Environment to as many Stages as you need.

Schema​

infrastructure:  
    environmentRef: ""  
    infrastructureDefinition:  
        type: ""  
        spec:  
            connectorRef: ""  
            namespace: ""  
            releaseName: release-""  
    allowSimultaneousDeployments: true|false

Example​

infrastructure:  
    environmentRef: <+input>  
    infrastructureDefinition:  
        type: KubernetesDirect  
        spec:  
            connectorRef: <+input>  
            namespace: <+input>  
            releaseName: release-<+INFRA_KEY>  
    allowSimultaneousDeployments: false

That example is for the platform agnostic Kubernetes infrastructure. For a different infrastructure, such as GCP, it would look slightly different:

 infrastructure:  
    environmentRef: <+input>  
    infrastructureDefinition:  
        type: KubernetesGcp  
        spec:  
            connectorRef: <+input>  
            cluster: <+input>  
            namespace: <+input>  
            releaseName: release-<+INFRA_KEY>  
    allowSimultaneousDeployments: false

See also:

Execution​

The stage Execution contains the steps for the stage.

Schema​

execution:  
    steps:  
        - step:  
              identifier: ""  
              name: ""  
              type: ""  
    rollbackSteps: []

Example​

Here is an example using the Shell Script step.

execution:  
    steps:  
        - step:  
              type: ShellScript  
              name: Step  
              identifier: Step  
              spec:  
                  shell: Bash  
                  onDelegate: true  
                  source:  
                      type: Inline  
                      spec:  
                          script: echo "hello"  
                  environmentVariables: []  
                  outputVariables: []  
                  executionTarget: {}  
              timeout: 10m  
    rollbackSteps: []

Steps and Step Groups​

A step is an individual operation in a stage.

Steps can be run in sequential and parallel order.

A Step Group is a collection of steps that share the same logic such as the same rollback strategy.

Schema​

Step:

- step:  
      identifier:   
      name:   
      type:

Step Group:

- stepGroup:  
      name:   
      identifier:   
      steps:  
          - step:  
                identifier:   
                name:   
                type:

Example​

Each step has different entries.

Here is an example of a Canary Deployment step.

- step:  
      name: Canary Deployment  
      identifier: canaryDeployment  
      type: K8sCanaryDeploy  
      timeout: 10m  
      spec:  
          instanceSelection:  
              type: Count  
              spec:  
                  count: 1  
          skipDryRun: false

See also:

Fixed Value, Runtime Input, and Expression​

You can use Fixed Value, Runtime Input, and Expressions for most settings.

  • Fixed value: The value is simply entered in the value of the key: value entry.
  • Runtime input: You simple enter <+input> in the value of the key: value entry.
  • Expression: You simply enter <+ in the value of the key: value entry and a list of available expressions appears. Select the expression to use.

See also:

Flow Control​

Barriers allow you to synchronize different stages in your Pipeline, and control the flow of your deployment systematically.

The Flow Control YAML is at the end of the Pipeline YAML, but it is not mandatory.

Schema​

pipeline:  
    name: ""  
    identifier: ""  
    projectIdentifier: ""  
    orgIdentifier: ""  
    tags: {}  
    stages:  
...  
    flowControl:  
        barriers:  
            - name: ""  
              identifier: ""

Example​

flowControl:  
    barriers:  
        - name: mybarrier  
          identifier: mybarrier

See also:

Notification Rules​

You can send Pipeline event notifications using email and popular communication and incident management platforms.

Event notifications are set up using Notification Rules in your Pipeline. You select the types of events to send, and then select how you want to send notifications. When those events occur, Harness sends event information to those channels and recipients.

The Notification Rules YAML is at the end of the Pipeline YAML, but it is not mandatory.

Schema​

pipeline:  
    name: ""  
    identifier: ""  
    projectIdentifier: ""  
    orgIdentifier: ""  
    tags: {}  
    stages:  
...  
    notificationRules:  
        - name: ""  
          pipelineEvents:  
              - type: ""  
          notificationMethod:  
              type: ""  
              spec:  
                  userGroups: []  
                  recipients:  
                      - ""  
          enabled: true|false

Example​

notificationRules:  
    - name: mynotification  
      pipelineEvents:  
          - type: AllEvents  
      notificationMethod:  
          type: Email  
          spec:  
              userGroups: []  
              recipients:  
                  - john.doe@harness.io  
      enabled: true

See also:

Triggers​

Triggers are used to automate the execution of Pipelines based on some event like new artifact/manifest, or run on a schedule or an external webhook.

Trigger YAML is not part of the main Pipeline YAML, but Triggers can be configure using YAML in the Triggers tab of the Pipeline.

Schema​

Webhook:

trigger:  
    name: ""  
    identifier: ""  
    enabled: true|false  
    description: ""  
    tags: {}  
    orgIdentifier: ""  
    projectIdentifier: ""  
    pipelineIdentifier: ""  
    source:  
        type: Webhook  
        spec:  
            type: Github  
            spec:  
                type: ""  
                spec:  
                    connectorRef: ""  
                    autoAbortPreviousExecutions: true|false  
                    payloadConditions:  
                        - key: ""  
                          operator: ""  
                          value: ""  
                        - key: ""  
                          operator: ""  
                          value: ""  
                        - key: ""  
                          operator: ""  
                          value: ""  
                    headerConditions: []  
                    actions: []

Schedule (Cron):

trigger:  
    name: ""  
    identifier: ""  
    enabled: true|false  
    tags: {}  
    orgIdentifier: ""  
    projectIdentifier: ""  
    pipelineIdentifier: ""  
    source:  
        type: Scheduled  
        spec:  
            type: Cron  
            spec:  
                expression: ""

Custom:

trigger:  
    name: ""  
    identifier: ""  
    enabled: true|false  
    description: ""  
    tags: {}  
    orgIdentifier: ""  
    projectIdentifier: ""  
    pipelineIdentifier: ""  
    source:  
        type: Webhook  
        spec:  
            type: Custom  
            spec:  
                payloadConditions: []  
                headerConditions: []

Example​

Here's a Webhook Trigger for a Pipeline with Runtime Input settings. Runtime Input settings in a Pipeline result in the inputYaml section of the Trigger.

trigger:  
    name: mytrigger  
    identifier: mytrigger  
    enabled: true  
    description: ""  
    tags: {}  
    orgIdentifier: default  
    projectIdentifier: CD_Examples  
    pipelineIdentifier: YAML  
    source:  
        type: Webhook  
        spec:  
            type: Github  
            spec:  
                type: PullRequest  
                spec:  
                    connectorRef: quickstart  
                    autoAbortPreviousExecutions: false  
                    payloadConditions:  
                        - key: changedFiles  
                          operator: Equals  
                          value: filename  
                        - key: sourceBranch  
                          operator: Equals  
                          value: foo  
                        - key: targetBranch  
                          operator: Equals  
                          value: bar  
                    headerConditions: []  
                    actions: []  
    inputYaml: |  
        pipeline:  
            identifier: YAML  
            stages:  
                - stage:  
                      identifier: Deploy  
                      type: Deployment  
                      spec:  
                          infrastructure:  
                              infrastructureDefinition:  
                                  type: KubernetesDirect  
                                  spec:  
                                      connectorRef: Kubernetes_Quickstart  
                                      namespace: default  
                - stage:  
                      identifier: Canary  
                      type: Deployment  
                      spec:  
                          infrastructure:  
                              environmentRef: helmchart  
                              infrastructureDefinition:  
                                  type: KubernetesDirect  
                                  spec:  
                                      connectorRef: Kubernetes_Quickstart  
                                      namespace: default

Input Sets and Overlays​

Harness Input Sets are collections of runtime inputs for a Pipeline provided before execution. Runtime inputs contain the values that you would be prompted to provide when you executed the Pipeline.

Overlays are groups of Input Sets. Overlays enable you to provide several Input Sets when executing a Pipeline.

Schema​

The Input Set YAML depends on the settings in your Pipeline that use Runtime Inputs.

Input Set:

inputSet:  
    name: ""  
    tags: {}  
    identifier: ""  
    orgIdentifier: ""  
    projectIdentifier: ""  
    pipeline:  
        identifier: ""  
        stages:  
            - stage:  
                  identifier: ""  
                  type: ""  
                  spec:  
                      infrastructure:  
                          infrastructureDefinition:  
                              type: ""  
                              spec:  
                                  connectorRef: ""  
                                  namespace: ""

Overlay:

overlayInputSet:  
    name: ""  
    identifier: ""  
    orgIdentifier: ""  
    projectIdentifier: ""  
    pipelineIdentifier: ""  
    inputSetReferences:  
        - ""  
        - ""  
    tags: {}

Example​

Input Set:

inputSet:  
    name: My Input Set 1  
    tags: {}  
    identifier: My_Input_Set  
    orgIdentifier: default  
    projectIdentifier: CD_Examples  
    pipeline:  
        identifier: YAML  
        stages:  
            - stage:  
                  identifier: Deploy  
                  type: Deployment  
                  spec:  
                      infrastructure:  
                          infrastructureDefinition:  
                              type: KubernetesDirect  
                              spec:  
                                  connectorRef: Kubernetes_Quickstart  
                                  namespace: default  
            - stage:  
                  identifier: Canary  
                  type: Deployment  
                  spec:  
                      infrastructure:  
                          environmentRef: helmchart  
                          infrastructureDefinition:  
                              type: KubernetesDirect  
                              spec:  
                                  connectorRef: Kubernetes_Quickstart  
                                  namespace: default

Overlay:

overlayInputSet:  
    name: My Overlay Set  
    identifier: My_Overlay_Set  
    orgIdentifier: default  
    projectIdentifier: CD_Examples  
    pipelineIdentifier: YAML  
    inputSetReferences:  
        - My_Input_Set  
        - My_Input_Set_2  
    tags: {}

See also:

Connectors​

Connectors contain the information necessary to integrate and work with 3rd party tools.

Harness uses Connectors at Pipeline runtime to authenticate and perform operations with a 3rd party tool.

In the visual editor, Connectors can be added inline as your build your Pipeline.

In YAML editor, Connectors are not configured inline. You can only reference existing Connectors.

When you create a Connector, you can use YAML.

Here's what the YAML for a Connector looks like:

connector:  
    name: cd-doc  
    identifier: cddoc  
    description: ""  
    orgIdentifier: default  
    projectIdentifier: CD_Examples  
    type: K8sCluster  
    spec:  
        credential:  
            type: InheritFromDelegate  
        delegateSelectors:  
            - example

You reference a connector in your pipeline by using its Id in connectorRef:

...  
infrastructureDefinition:  
    type: KubernetesDirect  
    spec:  
        connectorRef: cddoc  
        namespace: default  
        releaseName: release-<+INFRA_KEY>  
...