Migration Guide

Learn how to migrate from Harness NextGen (NG) to Harness 3.0.

This guide provides a step-by-step process for migrating from Harness NG to Harness 3.0. Existing NG resources are fully compatible with 3.0, so teams can migrate incrementally at their own pace.

NO DOWNTIME REQUIRED

Migration to Harness 3.0 does not require downtime. Existing NG pipelines, connectors, secrets, and other resources continue to work without modification. The migration process is additive; you adopt new features when ready.

Setup

Follow these eight steps to migrate from Harness NG to Harness 3.0. Each step can be performed independently, and you can proceed at whatever pace suits your team.

Review Existing Pipelines: Audit your existing NG pipelines to understand their structure, stage types, and dependencies. Identify pipelines that would benefit most from the v1 YAML format.
Simplify YAML: Convert pipeline YAML from the NG format to the v1 specification. Remove boilerplate fields like projectIdentifier and orgIdentifier that are no longer required at the pipeline level.
Remove Stage Types: In v1 YAML, explicit stage type wrappers are simplified. The type: Deployment with nested spec.deploymentType is replaced with a flat type: deploy or type: ci.
Add Typed Inputs: Replace runtime inputs (<+input>) with the new typed inputs system. Typed inputs support string, number, boolean, choice, and secret types with validation and default values.
Deploy Delegate 3.0: Install the new unified Delegate 3.0 alongside existing delegates. Route new pipelines to Delegate 3.0 using delegate selectors, and decommission NG delegates as workloads are migrated.
Customize Navigation: Explore the new 3.0 navigation layout. Pin frequently used projects and resources, configure your sidebar preferences, and learn the keyboard shortcuts for efficient navigation.
Explore Harness Code: Harness Code is the built-in source code management system in Harness 3.0. Evaluate whether migrating repositories to Harness Code can simplify your pipeline configurations and reduce external dependencies.
Use Harness AI: Leverage the reimagined AI Assistant to accelerate your migration. It can help create new v1 pipelines, explain configuration differences, and troubleshoot issues during the transition.

The following example shows a side-by-side comparison of the same pipeline expressed in the NG format and the 3.0 v1 format. The v1 format is significantly shorter and easier to read.

Before: Harness NG YAML

# Harness NG (v0 YAML) <a href="#harness-ng-v0-yaml" id="harness-ng-v0-yaml"></a>
pipeline:
  name: Deploy App
  identifier: deploy_app
  projectIdentifier: my_project
  orgIdentifier: default
  stages:
    - stage:
        name: Deploy to Dev
        identifier: deploy_dev
        type: Deployment
        spec:
          deploymentType: Kubernetes
          service:
            serviceRef: my_service
          environment:
            environmentRef: dev
            deployToAll: false
            infrastructureDefinitions:
              - identifier: k8s_dev
          execution:
            steps:
              - step:
                  name: Rolling Deploy
                  identifier: rolling
                  type: K8sRollingDeploy
                  spec:
                    skipDryRun: false

After: Harness 3.0 YAML

# Harness 3.0 (v1 YAML) <a href="#harness-30-v1-yaml" id="harness-30-v1-yaml"></a>
pipeline:
  name: Deploy App
  stages:
    - name: Deploy to Dev
      service: my_service
      environment:
        name: dev
        deploy-to: k8s_dev
      steps:
        - name: Rolling Deploy
          with:
            skip_dry_run: false

KEY DIFFERENCES

The v1 format removes projectIdentifier, orgIdentifier, and identifier fields (inferred from context), flattens the stage and step hierarchy, and replaces nested serviceRef / environmentRef with top-level service and environment fields.