Workflow Validation

Overview

Hyve validates workflows before execution to catch errors early and provide clear feedback. Validation checks YAML syntax, required fields, tool availability, secret presence, and more.

YAML Validation

Verify syntax and structure

Tool Checks

Ensure required tools are installed

Secret Validation

Verify secrets are available

Early Errors

Catch problems before execution

Validation Phases

Hyve performs validation in multiple phases:

1. YAML Syntax

Checks that the workflow file is valid YAML

[ERROR] Invalid YAML syntax in workflow 'deploy-app'
[ERROR] Line 10: mapping values are not allowed here

2. Schema Validation

Verifies required fields and structure

[ERROR] Workflow validation failed:
- Missing required field: metadata.name
- Missing required field: spec.jobs

3. Requirements Validation

Checks tools and secrets are available

[INFO] Validating workflow requirements...
[ERROR] Required tool 'kubectl' not found in PATH
[ERROR] Required secret 'DOCKER_TOKEN' not found

4. Runtime Validation

Validates during execution (variable substitution, commands)

[INFO] Executing workflow 'deploy-app'
[ERROR] Command failed: kubectl apply -f manifests/

YAML Syntax Validation

Hyve checks that workflow files are valid YAML:

Valid YAML

apiVersion: v1
kind: Workflow
metadata:
  name: deploy-app
spec:
  jobs:
    - name: deploy
      steps:
        - name: apply
          command: kubectl apply -f manifests/

Invalid YAML Examples

Missing Colon

# Invalid - missing colon after 'name'
metadata:
  name deploy-app  # ❌ Missing colon

# Valid
metadata:
  name: deploy-app  # ✅ Correct

Wrong Indentation

# Invalid - incorrect indentation
spec:
  jobs:
  - name: deploy  # ❌ Wrong indentation
    steps:
      - name: apply

# Valid
spec:
  jobs:
    - name: deploy  # ✅ Correct indentation
      steps:
        - name: apply

Mixed Tabs/Spaces

# Invalid - mixing tabs and spaces
spec:
→env:  # ❌ Tab character
  APP_NAME: my-app  # Spaces

# Valid - use spaces consistently
spec:
  env:  # ✅ Spaces only
    APP_NAME: my-app

Schema Validation

Hyve validates the workflow structure and required fields:

Required Fields

apiVersion string required

Must be v1

kind string required

Must be Workflow

metadata.name string required

Unique workflow identifier

spec.jobs array required

At least one job must be defined

spec.jobs[].name string required

Each job must have a name

spec.jobs[].steps array required

Each job must have at least one step

Common Schema Errors

Missing Required Fields

# Invalid - missing metadata.name
apiVersion: v1
kind: Workflow
metadata:
  description: Deploy app
# ❌ Missing: metadata.name

# Valid
apiVersion: v1
kind: Workflow
metadata:
  name: deploy-app
  description: Deploy app

Empty Jobs Array

# Invalid - no jobs defined
spec:
  jobs: []  # ❌ Empty array

# Valid - at least one job
spec:
  jobs:
    - name: deploy
      steps:
        - name: apply
          command: kubectl apply -f manifests/

Missing Step Command

# Invalid - step has no command or script
steps:
  - name: deploy  # ❌ No command or script

# Valid - step has command
steps:
  - name: deploy
    command: kubectl apply -f manifests/

Both Command and Script

# Invalid - can't have both
steps:
  - name: deploy
    command: kubectl apply -f manifests/  # ❌
    script: |  # ❌ Can't have both
      kubectl apply -f manifests/

# Valid - use one or the other
steps:
  - name: deploy
    command: kubectl apply -f manifests/

Requirements Validation

Before executing, Hyve validates that requirements are met:

Tool Validation

Checks that required tools are installed:

requirements:
  tools:
    - name: kubectl
      version: "1.28"
    - name: helm
      version: "3.12"

Validation checks:

Tool exists in PATH
Version meets minimum requirement (if specified)

Error messages:

[ERROR] Requirements validation failed:
  - Required tool 'kubectl' not found in PATH
  - Tool 'helm' version mismatch: found 3.10.0, requires 3.12

Secret Validation

Checks that required secrets are available:

requirements:
  secrets:
    - name: DOCKER_TOKEN
      provider: docker
      required: true
    - name: GITHUB_TOKEN
      provider: github
      required: false

Validation checks:

Secret exists in environment or database
Required secrets must be present
Optional secrets show warnings if missing

Error messages:

[ERROR] Requirements validation failed:
  - Required secret 'DOCKER_TOKEN' not found
    Set via: export DOCKER_TOKEN=your-secret

[WARN] Optional secret 'GITHUB_TOKEN' not found

Manual Validation

Validate workflows without running them:

# Validate specific workflow
hyve workflow validate deploy-app

# Validate all workflows in repository
hyve workflow validate --all

Output:

[INFO] Validating workflow 'deploy-app'
[INFO] ✅ YAML syntax valid
[INFO] ✅ Schema validation passed
[INFO] ✅ Requirements validation passed
[INFO] Workflow 'deploy-app' is valid

Dry Run

Preview workflow execution without actually running it:

# Dry run workflow
hyve workflow run deploy-app --dry-run

Output:

[INFO] DRY RUN: Workflow 'deploy-app'
[INFO] Would execute:

Job: build
  Step: docker-build
    Command: docker build -t my-app:latest .

Job: deploy
  Step: kubectl-apply
    Command: kubectl apply -f manifests/

[INFO] DRY RUN: No changes made

Common Validation Errors

Invalid YAML syntax

Error:

[ERROR] Invalid YAML syntax in workflow 'deploy-app'
[ERROR] Line 10: mapping values are not allowed here

Solution:

Check for missing colons
Verify indentation (use spaces, not tabs)
Ensure proper YAML structure

Missing required field

Error:

[ERROR] Workflow validation failed:
- Missing required field: metadata.name

Solution:

# Add missing field
metadata:
  name: my-workflow

Tool not found

Error:

[ERROR] Required tool 'kubectl' not found in PATH

Solution:

# Install missing tool
brew install kubectl

# Verify installation
kubectl version --client

Tool version mismatch

Error:

[ERROR] Tool 'helm' version mismatch: found 3.10.0, requires 3.12

Solution:

# Update tool
brew upgrade helm

# Or adjust workflow requirement
requirements:
  tools:
    - name: helm
      version: "3.10"  # Lower requirement

Secret not found

Error:

[ERROR] Required secret 'DOCKER_TOKEN' not found

Solution:

export DOCKER_TOKEN=your-token

Invalid job dependency

Error:

[ERROR] Job 'deploy' depends on non-existent job 'build'

Solution:

# Ensure referenced job exists
jobs:
  - name: build  # ✅ Add missing job
    steps:
      - name: build
        command: make build

  - name: deploy
    dependsOn: [build]  # Now valid
    steps:
      - name: deploy
        command: make deploy

Circular dependency

Error:

[ERROR] Circular dependency detected: build → deploy → build

Solution:

# Remove circular dependency
jobs:
  - name: build
    steps:
      - name: build
        command: make build

  - name: deploy
    dependsOn: [build]  # ✅ One-way dependency
    steps:
      - name: deploy
        command: make deploy

Best Practices

1. Validate Before Committing

# Validate workflow
hyve workflow validate deploy-app

# If valid, commit
git add workflows/deploy-app.yaml
git commit -m "Add deployment workflow"

2. Use Dry Run for Testing

# Test workflow without executing
hyve workflow run deploy-app --dry-run

# Review output, then run for real
hyve workflow run deploy-app

3. Specify Tool Versions

# Good - specific versions
requirements:
  tools:
    - name: kubectl
      version: "1.28"
    - name: helm
      version: "3.12"

# Less safe - no version check
requirements:
  tools:
    - name: kubectl
    - name: helm

4. Test in Development First

# Switch to development
hyve git use development

# Test new workflow
hyve workflow validate new-workflow
hyve workflow run new-workflow --dry-run
hyve workflow run new-workflow

# If successful, use in production
hyve git use production

5. Use Schema Validation Tools

# Use YAML linters
yamllint workflows/deploy-app.yaml

# Check with Hyve validator
hyve workflow validate deploy-app

Validation in CI/CD

Add validation to your CI/CD pipeline:

name: Validate Hyve Workflows

on:
  pull_request:
    paths:
      - 'workflows/**.yaml'

jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3

      - name: Install Hyve
        run: |
          # Install Hyve
          go install github.com/cbridges1/hyve@latest

      - name: Validate workflows
        run: |
          hyve workflow validate --all

Validation Output

Successful Validation

[INFO] Validating workflow 'deploy-app'
[INFO] ✅ YAML syntax valid
[INFO] ✅ Schema validation passed
[INFO] ✅ Requirements validation passed
[INFO] ✅ Tool 'kubectl' found (version 1.28.0)
[INFO] ✅ Tool 'helm' found (version 3.12.0)
[INFO] ✅ Secret 'DOCKER_TOKEN' found
[INFO] Workflow 'deploy-app' is valid

Failed Validation

[INFO] Validating workflow 'deploy-app'
[ERROR] ✗ YAML syntax invalid
[ERROR] Line 10: mapping values are not allowed here
[ERROR] Validation failed

Please fix the errors and try again.

Partial Validation (Warnings)

[INFO] Validating workflow 'deploy-app'
[INFO] ✅ YAML syntax valid
[INFO] ✅ Schema validation passed
[WARN] ⚠ Optional secret 'GITHUB_TOKEN' not found
[INFO] ✅ Tool 'kubectl' found (version 1.28.0)
[INFO] Workflow 'deploy-app' is valid with warnings

Workflow Overview

Complete workflow guide

Requirements

Tool and secret validation

Variables

Variable substitution

Workflow Concepts

Workflow fundamentals

Workflow Validation

Overview

Validation Phases

YAML Syntax Validation

Valid YAML

Invalid YAML Examples

Schema Validation

Required Fields

Common Schema Errors

Requirements Validation

Tool Validation

Secret Validation

Manual Validation

Dry Run

Common Validation Errors

Best Practices

Validation in CI/CD

Validation Output

Successful Validation

Failed Validation

Partial Validation (Warnings)

Related