Creating pipelines

Create Pipeline

What this skill uses

Harness MCP tools: harness:harness_create, harness:harness_execute, harness:harness_get, harness:harness_list, harness:harness_schema, harness:harness_status, harness:harness_update Resource types: connector, pipeline References: references/codebase-analysis.md, references/native-steps.md, references/v0-pipeline-schema.md

Generate Harness v0 Pipeline YAML and optionally push to Harness via MCP.

Stage / step / variable / parallel / failure / matrix / conditional syntax: see references/syntax-reference.md. Complete CI and CD pipeline examples: see references/full-examples.md.

Schema discovery (do this first)

Before hand-rolling YAML, fetch the live schema from the MCP. It is authoritative and saves you guessing field names. Use these calls in order:

• harness:harness_schema(resource_type='pipeline') for top-level summary of fields and sections.
• harness:harness_schema(resource_type='pipeline', path='<dotted.section>') to drill into a specific section.
• harness:harness_schema(resource_type='pipeline', example_search='<keyword>') to find a working example.
• harness:harness_schema(resource_type='pipeline', example='<example-name>') to fetch the full example YAML.

If a section is more complex than expected, drill into it with path instead of asking the user. Only fall back to authoring without schema lookup if the resource type is not in the bundled schemas list.

Instructions

1. Analyze codebase (if source code is available) - Scan the project to auto-detect language, build tools, test frameworks, containerization, deployment manifests, and target infrastructure. Use the detection tables and decision tree in references/codebase-analysis.md to determine:
   • Language and runtime version (package.json -> Node.js, go.mod -> Go, pom.xml -> Java, etc.)
   • Build commands and base images
   • Test framework and report format (Jest -> JUnit, pytest -> JUnit XML, etc.)
   • Linter and formatter (ESLint, Prettier, Ruff, etc.)
   • Dockerfile presence and registry type (Docker Hub, ECR, GCR, ACR)
   • Deployment manifests -> Harness service/deployment type (k8s manifests -> Kubernetes, Chart.yaml -> NativeHelm, task-definition.json -> ECS, serverless.yml -> ServerlessAwsLambda)
   • Existing CI/CD configs for migration (GitHub Actions, Jenkins, GitLab CI, etc.)
2. Clarify requirements - Confirm detected settings with the user. Ask about anything that couldn't be auto-detected - do not guess or use placeholders. If the user's request is ambiguous, ask before generating YAML. Examples of what to ask when missing:
   • Deployment target / infrastructure: region (e.g. us-east-1), cluster name or ID, account ID (e.g. AWS account for ECR/ECS)
   • Registry: which registry (Docker Hub, ECR, GCR, ACR), registry identifier/URL, repo path
   • Cloud provider: which account, region, and resource identifiers for connectors/infrastructure
   • Approval gates, notification channels if relevant Critical rule: Never hardcode placeholder values (e.g. 123456789012, us-east-1, my-cluster) for deployment target, region, registry, or cluster when the user did not specify them - ask the user instead. If the user did not specify region, account ID, cluster, or registry (e.g. "deploys to ECS" with no region or cluster), ask the user for those values before generating YAML.
3. Select native steps - Always prefer Harness native steps over Run or ShellScript steps. Consult references/native-steps.md for the full mapping. Key rules:
   • Docker build/push -> use BuildAndPushDockerRegistry / BuildAndPushECR / BuildAndPushGCR / BuildAndPushACR (never Run: docker build && docker push)
   • K8s deploy -> use K8sRollingDeploy / K8sBlueGreenDeploy / K8sCanaryDeploy (never Run: kubectl apply)
   • Helm deploy -> use HelmDeploy (never Run: helm upgrade --install)
   • ECS deploy -> use EcsRollingDeploy (never Run: aws ecs update-service)
   • Terraform -> use TerraformPlan / TerraformApply (never Run: terraform apply)
   • Security scanning -> use native STO steps (AquaTrivy, Snyk, Sonarqube, Semgrep, etc.)
   • Uploads -> use S3Upload / GCSUpload (never Run: aws s3 cp)
   • Approvals -> use HarnessApproval / JiraApproval (never polling scripts)
   • Ticketing -> use JiraCreate / ServiceNowCreate (never Run: curl)
   • Use Run steps only for custom build/test/lint commands with no native equivalent
   • Test steps: Any Run step that runs unit or integration tests must include a reports block (e.g. type: JUnit, spec.paths) so Harness can capture results; see references/codebase-analysis.md for framework -> report path.
4. Generate valid YAML following the structure below, using the detected build/test/deploy commands. Validation rules: (a) Stage names must match ^[a-zA-Z_0-9-.][-0-9a-zA-Z_\\s.]{0,127}$ - use only letters, numbers, spaces, hyphens, underscores, or periods (no commas). (b) Every CI and CD stage must include a failureStrategies array (Approval stages do not require one). For CI use MarkAsFailure (never Ignore - it hides failures); for CD use StageRollback.
5. Optionally create via MCP - First verify the project exists (see "Creating via MCP" section below), then use harness:harness_create with resource_type pipeline and body: { yamlPipeline: "<YAML string>" }

Pipeline Structure

pipeline:
  identifier: my_pipeline       # ^[a-zA-Z_][0-9a-zA-Z_]{0,127}$
  name: My Pipeline
  orgIdentifier: default
  projectIdentifier: my_project
  tags: {}
  properties:
    ci:
      codebase:                  # Required for CI stages
        connectorRef: github_connector
        repoName: my-repo
        build:
          type: branch
          spec:
            branch: <+trigger.branch>
  stages:
    - stage: ...

For stage-by-stage and step-by-step YAML syntax (CI / Deployment / Approval stages, Run / Docker / K8s / Approval steps, variables, parallel blocks, failure strategies, conditional execution, and matrix strategy placement), see references/syntax-reference.md.

Creating via MCP

After generating the YAML, create it in Harness:

1. Verify the project exists - List projects with harness:harness_list (resource_type: project, org_id) to confirm. If the project does not exist, create it first with harness:harness_create (resource_type: project, body: { identifier, name }) or ask the user.
2. Create the pipeline - Use harness:harness_create with the pipeline YAML serialized as a yamlPipeline string in the body. Do not pass a nested JSON pipeline object; it causes serialization errors.

Call MCP tool: harness:harness_create
Parameters:
  resource_type: "pipeline"
  org_id: "<organization>"
  project_id: "<project>"
  body: { yamlPipeline: "<full pipeline YAML string, including 'pipeline:' root key>" }

Example body (abbreviated):

{
  "yamlPipeline": "pipeline:\n  identifier: nodejs_ci\n  name: Node.js CI\n  projectIdentifier: my_project\n  orgIdentifier: default\n  stages:\n    - stage:\n        identifier: build\n        ..."
}

To update an existing pipeline, use the same yamlPipeline format:

Call MCP tool: harness:harness_update
Parameters:
  resource_type: "pipeline"
  resource_id: "<pipeline_identifier>"
  org_id: "<organization>"
  project_id: "<project>"
  body: { yamlPipeline: "<full updated pipeline YAML string>" }

To verify it was created:

Call MCP tool: harness:harness_get
Parameters:
  resource_type: "pipeline"
  resource_id: "<pipeline_identifier>"
  org_id: "<organization>"
  project_id: "<project>"

Examples

For full end-to-end CI and CD pipeline YAML (Node.js CI with parallel lint/test and Docker push; multi-stage Kubernetes deploy with staging, manual approval, and production rollback), see references/full-examples.md.

Trigger prompts

/creating-pipelines
Create a CI pipeline for a Node.js app that builds, runs tests, and pushes to Docker Hub

/creating-pipelines
Create a Kubernetes deployment pipeline with staging, manual approval, and production stages

/creating-pipelines
Build a pipeline that runs tests, pushes a Docker image, and deploys to ECS with rollback

/creating-pipelines
Create a CI pipeline that tests across Node 16, 18, and 20 on both Linux and macOS

/creating-pipelines
Create a pipeline with parallel test stages for unit tests, integration tests, and linting

Related skills

Prerequisites (skills typically run before this one):

• /creating-services
• /creating-environments
• /creating-infrastructures
• /creating-connectors
• /managing-secrets

Composes with (skills commonly invoked together):

• /managing-templates
• /creating-triggers

Follow-ups (skills commonly chained after this one):

• /running-pipelines
• /debugging-pipelines
• /creating-policies

Performance Notes

• Always check references/native-steps.md before using a Run step. Native steps provide better error handling and UI integration.
• Verify the target project exists (harness:harness_list, resource_type: project) before creating the pipeline.
• Validate that all referenced connectors, services, and environments exist before creating the pipeline.
• For CD pipelines, confirm the deployment type matches the service definition type.
• Quality of generated YAML is more important than speed. Verify structure before submitting.

Troubleshooting

YAML Validation Errors

• Pipeline/step identifier: must match ^[a-zA-Z_][0-9a-zA-Z_]{0,127}$ (letters, numbers, underscores only).
• Stage name: must match ^[a-zA-Z_0-9-.][-0-9a-zA-Z_\\s.]{0,127}$ - no commas; use letters, numbers, spaces, hyphens, underscores, or periods (e.g. use "Build Test and Push" not "Build, Test and Push").
• Every CI and CD stage must include a failureStrategies array (Approval stages do not require one); omit it and the API returns "failureStrategies: is missing but it is required". For CI use type: MarkAsFailure; for CD use type: StageRollback.
• Stage type is case-sensitive: CI, Deployment, Approval, Custom
• Every stage must have a spec field
• Matrix not applied / not visible in UI: strategy must be a sibling of spec on the stage, not inside spec. Use strategy.matrix at the stage level and reference values as <+stage.matrix.TAG>.
• HarnessApproval: "disallowPipelineExecutor: is missing but it is required" - add approvers.disallowPipelineExecutor: true to the step spec.

MCP Creation Errors

• Project not found - Verify the project exists with harness:harness_list (resource_type: project, org_id). Create it first with harness:harness_create (resource_type: project, body: { identifier, name }) or confirm org_id/project_id are correct.
• Missing required fields for pipeline: pipeline - Pass the body as { yamlPipeline: "<full pipeline YAML string>" } instead of a nested JSON pipeline object. Nested JSON causes serialization errors.
• DUPLICATE_IDENTIFIER - Pipeline already exists; use harness:harness_update instead
• CONNECTOR_NOT_FOUND - Create the connector first or fix connectorRef
• ACCESS_DENIED - Check API key permissions

Ambiguous or Incomplete Requests

• "Deploys to ECS" / "K8s deploy" / "push to registry" with no specifics - Ask the user for region, account ID, cluster name/ID, and which registry (ECR, Docker Hub, etc.) before generating YAML. Do not insert placeholder values (e.g. us-east-1, 123456789012).

Execution Failures

• Missing <+input> values - provide via input sets or runtime inputs
• Connector auth expired - test with harness:harness_execute (resource_type: "connector", action: "test_connection")
• Delegate offline - check with harness:harness_status