Harness Pipeline Design

Harness Pipeline Design

Purpose

Produce complete, schema-valid Harness pipeline YAML that follows enterprise engineering standards: parameterized inputs, environment promotion, integrated verification, and chaos-ready stage structure.

---

Input Contract

| Input | Source | Required | |---|---|---| | PRD / BA analysis output | s01 (workflowcontext.prd) | Yes | | Service name, artifact source, stack info | s01 context | Yes | | Environment tier list (dev/staging/prod) | s01 context or user | Yes | | Deploy strategy preference | s02 taste (deployment category) | No (defaults to Rolling) | | Approval mechanism preference | s02 taste (risktolerance) | No | | Observability tool preference | s02 taste (observability) | No | | Harness account/project identifiers | User or CLAUDE.md | Yes |

Output Contract

| Output | Destination | Format | |---|---|---| | Pipeline YAML | .commandcode/artifacts/pipeline-.yaml | YAML | | Trigger config YAML | .commandcode/artifacts/trigger-.yaml | YAML | | Pipeline context (for s05, s12, s19) | workflow_context.artifacts | YAML object | | Input set templates per env | .commandcode/artifacts/inputset-.yaml | YAML |

---

Prerequisites

Before generating any pipeline, confirm:

• [ ] Harness Account ID and Organization / Project identifiers known
• [ ] Target deployment type: Kubernetes / ECS / Lambda / VM / Custom
• [ ] Artifact source: Docker registry / ECR / GCR / Nexus / Artifactory
• [ ] Environment tiers required: dev → staging → preprod → prod
• [ ] Approval mechanism: automatic / manual / JIRA / ServiceNow
• [ ] Observability stack: Prometheus / Datadog / New Relic / AppDynamics

If any item is unknown, surface a question to the user before generating YAML.

---

Pipeline Anatomy

Pipeline
├── Variables (runtime inputs, expressions)
├── Stages
│   ├── CI Stage (Build + Test + Push)
│   │   ├── Steps: Clone → Build → Unit Test → SAST → Push
│   │   └── Caching: Intelligence cache / S3 cache
│   ├── CD Stage (Deploy)
│   │   ├── Service (artifact + manifests)
│   │   ├── Environment (infrastructure definition)
│   │   ├── Execution
│   │   │   ├── Pre-deployment: secrets sync, DB migration
│   │   │   ├── Deploy step: Rolling / Canary / Blue-Green
│   │   │   ├── Chaos step (optional, see chaos/01-experiment-design)
│   │   │   └── Verify step (CV — see harness/06-cv-verification)
│   │   └── Rollback (auto on failure)
│   └── Approval Stage (between envs)
└── Notification Rules (Slack / email / PagerDuty)

---

Workflow

Step 1 — Gather Parameters

Collect via conversation or structured input:

service_name:       # e.g., payment-service
artifact_image:     # e.g., gcr.io/myproject/payment-service
environments:       # [dev, staging, prod]
deploy_strategy:    # rolling | canary | blueGreen
k8s_namespace:      # e.g., payments
approval_type:      # none | manual | jira
chaos_enabled:      # true | false
cv_enabled:         # true | false

Step 2 — Scaffold Pipeline YAML

Generate from the canonical template below. Replace `` tokens.

Step 3 — Validate

Run mental schema check:

• All identifier fields: [a-zA-Z_][a-zA-Z0-9_]* (no hyphens)
• All name fields: human-readable, spaces allowed
• No hardcoded secrets (use `` expressions)
• Expression syntax: `, , `

Step 4 — Output

Return complete YAML with inline comments explaining non-obvious fields.

---

Canonical Pipeline Template

# Generated by: hybrid-harness-chaos-process-prm
pipeline:
  name: -pipeline
  identifier: _pipeline
  projectIdentifier: 
  orgIdentifier: 
  description: "CI/CD pipeline for "
  tags:
    managed-by: hcprm
    service: 

  variables:
    - name: imageTag
      type: String
      description: "Docker image tag to deploy"
      required: true
      value: 
    - name: targetEnv
      type: String
      description: "Target environment"
      required: true
      value: .allowedValues(dev,staging,preprod,prod)

  stages:
    # ─────────────────────────────────────────────
    # Stage 1: CI — Build and Push
    # ─────────────────────────────────────────────
    - stage:
        name: Build
        identifier: Build
        type: CI
        spec:
          cloneCodebase: true
          caching:
            enabled: true
            paths:
              - node_modules
              - .gradle/caches
          execution:
            steps:
              - step:
                  name: Run Unit Tests
                  identifier: run_unit_tests
                  type: Run
                  spec:
                    connectorRef: account.dockerhub
                    image: node:20-alpine
                    command: |
                      npm ci
                      npm test -- --coverage
                    reports:
                      type: JUnit
                      spec:
                        paths:
                          - "**/junit.xml"
              - step:
                  name: Build and Push Image
                  identifier: build_push_image
                  type: BuildAndPushDockerRegistry
                  spec:
                    connectorRef: account.dockerhub
                    repo: /
                    tags:
                      - 
                      - latest

    # ─────────────────────────────────────────────
    # Stage 2: Deploy to Environment
    # ─────────────────────────────────────────────
    - stage:
        name: Deploy 
        identifier: Deploy_
        type: Deployment
        spec:
          deploymentType: Kubernetes
          service:
            serviceRef: _svc
            serviceInputs:
              serviceDefinition:
                type: Kubernetes
                spec:
                  artifacts:
                    primary:
                      primaryArtifactRef: primary
                      sources:
                        - identifier: primary
                          spec:
                            tag: 
          environment:
            environmentRef: 
            deployToAll: false
            infrastructureDefinitions:
              - identifier: 
          execution:
            steps:
              - stepGroup:
                  name: Pre-Deployment
                  identifier: pre_deployment
                  steps:
                    - step:
                        name: Sync Secrets
                        identifier: sync_secrets
                        type: ShellScript
                        spec:
                          shell: Bash
                          source:
                            type: Inline
                            spec:
                              script: |
                                echo "Syncing secrets for "
                                # Add secret sync logic here
                          onDelegate: true
              - step:
                  name: Rolling Deploy
                  identifier: rolling_deploy
                  type: K8sRollingDeploy
                  spec:
                    skipDryRun: false
                    pruningEnabled: true
              # ── Chaos Step (inject after deploy, before verify) ──
              # See chaos/01-experiment-design for full config
              # - step:
              #     name: Chaos Experiment
              #     identifier: chaos_experiment
              #     type: Chaos
              #     spec:
              #       experimentRef: 
              #       expectedResilienceScore: 80
              #
              # ── Continuous Verification ──
              # See harness/06-cv-verification for full config
              # - step:
              #     name: Verify Deployment
              #     identifier: verify_deployment
              #     type: Verify
              #     spec:
              #       isMultiServicesOrEnvs: false
              #       type: Canary
              #       monitoredServiceRef: 
              #       healthSources: []
              #       duration: 10m
            rollbackSteps:
              - step:
                  name: Rollback Deployment
                  identifier: rollback_deployment
                  type: K8sRollingRollback
                  spec: {}

    # ─────────────────────────────────────────────
    # Stage 3: Approval Gate (between envs)
    # ─────────────────────────────────────────────
    - stage:
        name: Approve Production
        identifier: Approve_Production
        type: Approval
        spec:
          execution:
            steps:
              - step:
                  name: Production Approval
                  identifier: production_approval
                  type: HarnessApproval
                  spec:
                    approvalMessage: |
                      Approve deployment of 
                      to production environment?
                    includePipelineExecutionHistory: true
                    approvers:
                      minimumCount: 2
                      disallowPipelineExecutor: true
                      userGroups:
                        - account.SRE_Team
                        - account.Engineering_Leads
                    approverInputs:
                      - name: releaseNotes
                        defaultValue: ""
                    autoApproval:
                      action: REJECT
                      scheduledDeadline:
                        timeZone: UTC
                        time: "23:59"
        when:
          pipelineStatus: Success
          condition:  == "prod"

---

Deploy Strategy Variants

Read references/deploy-strategies.md for full Canary and Blue-Green templates.

Quick reference:

| Strategy | Use When | Rollback Speed | |---|---|---| | Rolling | Low risk, stateless services | Medium (re-deploy old) | | Canary | Need traffic split validation | Fast (route 0% to canary) | | BlueGreen | Zero-downtime, instant cutover | Instant (swap service selector) |

---

Trigger Configuration

# Webhook trigger for main branch push
trigger:
  name: On Main Push
  identifier: on_main_push
  type: Webhook
  spec:
    type: Github
    spec:
      type: Push
      spec:
        connectorRef: account.github_connector
        repoName: /
        autoAbortPreviousExecutions: true
        payloadConditions:
          - key: targetBranch
            operator: Equals
            value: main
      headerConditions: []
  inputYaml: |
    pipeline:
      identifier: _pipeline
      variables:
        - name: imageTag
          value: 

---

Expression Cheat Sheet

| Expression | Resolves To | |---|---| | ` | Full image URI | | | Image tag | | | Environment name | | | PreProduction / Production | | | Kubernetes namespace | | | Current execution UUID | | | Git commit SHA (webhook) | | | Secret value (never logs) | | ` | Cross-stage output |

---

AI Agent Integration

Autonomy Level

| Aspect | Level | Description | |---|---|---| | Current | L2 | AI generates pipeline YAML from natural language | | Target | L3 | AI generates and validates pipelines, human reviews |

Harness AI Agent

Agent: Harness AI DevOps Agent (Claude Opus 4.5 via Vertex AI) Capabilities:

• Natural language pipeline YAML generation across all modules
• Error Analyzer (change impact + dependency checks + historical patterns + RCA + fix recommendations)
• Pipeline Summarizer
• Multi-stage pipeline creation validated with 50-stage pipelines

Human Gates

• Pipeline approval before first deployment
• Security-sensitive stage configuration
• Production environment pipeline changes

Fallback

When Harness AI is unavailable: Use static pipeline templates from s09 Template Library and manual YAML construction following Harness schema documentation.

---

Success Criteria

• [ ] Pipeline YAML passes harness pipeline lint (or manual schema review)
• [ ] No hardcoded credentials
• [ ] All stages have rollback steps
• [ ] At minimum one health check or CV step before marking success
• [ ] Trigger configured and tested

---

Common Pitfalls

• Identifier contains hyphen → Harness will reject; use underscore
• Missing when conditions → stages run unconditionally, including approval in dev
• Hardcoded image tags → use `` instead
• No pruningEnabled → stale Kubernetes resources accumulate over time

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: dungnotnull
• Source: dungnotnull/hybrid-harness-chaos-process-prm
• License: MIT

Install and usage instructions live in the source repository linked above.