Skip to content
Hyve
Docs

Workflow Requirements

Overview

Hyve workflows support a requirements field that validates prerequisites before execution. This ensures all necessary CLI tools and secrets are available, preventing runtime failures with clear error messages.

Features

Tool Validation

Check if CLI tools are available in PATH with optional version checking

Secret Management

Check that required secrets are set as environment variables before the workflow runs

Clear Errors

Helpful error messages when requirements aren’t met

Suggestion Hints

A handful of recognized provider values (civo, aws, gcp, azure) customize the suggested fix in the error message

Requirement Types

Tool Requirements

Validate that CLI tools are installed and meet minimum version requirements.

requirements:
  tools:
    - name: kubectl
      version: "1.28"
      description: Kubernetes CLI for cluster operations
    - name: helm
      version: "3.12"
      description: Helm package manager
    - name: docker
      description: Docker CLI (version check optional)
name string required

Tool command name (e.g., kubectl, helm, docker)

version string

Minimum version required (optional)

description string

Human-readable description for error messages

Secret Requirements

Validate that secrets are set as environment variables.

requirements:
  secrets:
    - name: DOCKER_TOKEN
      provider: docker
      required: true
      description: Docker Hub authentication token
    - name: GITHUB_TOKEN
      provider: github
      required: false
      description: GitHub token (optional)
name string required

Environment variable name (e.g., DOCKER_TOKEN)

provider string

Optional. Customizes the suggested fix shown in the error message for a small set of recognized values (civo, aws, gcp, azure — e.g. suggesting aws configure). Doesn’t change how the secret is looked up — that’s always the environment variable named by name, regardless of provider.

required boolean default: true

Whether this secret is mandatory

description string

Human-readable description with instructions

Complete Example

apiVersion: v1
kind: Workflow
metadata:
  name: k8s-deploy
  description: Deploy to Kubernetes with validation
spec:
  requirements:
    tools:
      - name: kubectl
        version: "1.28"
        description: Kubernetes CLI
      - name: helm
        version: "3.12"
        description: Helm package manager
    secrets:
      - name: REGISTRY_TOKEN
        provider: registry
        required: true
        description: Container registry token
      - name: DATADOG_API_KEY
        provider: datadog
        required: false
        description: Monitoring API key (optional)


  env:
    APP_NAME: my-app
    NAMESPACE: default


  jobs:
    - name: deploy
      steps:
        - name: helm-deploy
          command: helm upgrade --install ${APP_NAME} ./charts

Setting Up Secrets

There is exactly one place a required secret is looked up: os.Getenv(name). Set it before running the workflow, however suits your environment:

Terminal window
export DOCKER_TOKEN=my-docker-token
hyve workflow run docker-build

For CI/CD, set secrets as pipeline secrets (e.g., GitHub Actions secrets) forwarded into the job’s env: block. For a Civo-specific secret, running civo apikey save/civo apikey use is not enough on its own — it writes to ~/.civo.json, which this check never reads; you still need to export the value under the exact name the workflow requires.

Secret Loading

When a workflow requires a secret, the check is a single step: is $SECRET_NAME set in the process environment? If yes, validation passes. If not and required: true, the workflow fails before any job runs, with an error naming the secret and (if provider is one of the recognized values) a suggested command. required: false secrets that aren’t set are simply skipped — not an error.

Error Messages

Missing Tool

Requirements validation failed:
  - Required tool 'helm' not found in PATH (Helm package manager)

Version Mismatch

Requirements validation failed:
  - tool 'kubectl' version mismatch: found 1.26.0, requires 1.28

Missing Secret

Requirements validation failed:
  - Required secret 'DOCKER_TOKEN' not found (Docker Hub authentication token)
    Set via: export DOCKER_TOKEN=your-secret

Multiple Errors

Requirements validation failed:
  - Required tool 'helm' not found in PATH (Helm package manager)
  - Required secret 'DOCKER_TOKEN' not found (Docker Hub authentication token)
    Set via: export DOCKER_TOKEN=your-secret
  - Required secret 'GITHUB_TOKEN' not found (GitHub API token)
    Set via: export GITHUB_TOKEN=your-secret

Successful Validation

When all requirements are met:

[INFO] Starting workflow 'docker-build'
[INFO] Validating workflow requirements...
[INFO] ✅ All requirements validated successfully
[INFO][validate-environment] Starting job 'validate-environment'

Best Practices

1. Be Specific with Versions

Always specify minimum versions for critical tools:

requirements:
  tools:
    - name: kubectl
      version: "1.28"  # Specify minimum version
2. Add Helpful Descriptions

Include descriptions with instructions or URLs:

requirements:
  secrets:
    - name: DOCKER_TOKEN
      provider: docker
      required: true
      description: Get token from https://hub.docker.com/settings/security
3. Mark Optional Secrets

Use required: false for optional features:

requirements:
  secrets:
    - name: DATADOG_API_KEY
      provider: datadog
      required: false  # Won't fail if missing
      description: Monitoring is optional
4. Group Related Requirements

Organize requirements by purpose:

requirements:
  tools:
    # Container tools
    - name: docker
      version: "20.10"
    - name: buildx


    # Kubernetes tools
    - name: kubectl
      version: "1.28"
    - name: helm
      version: "3.12"

Examples

Docker Build Workflow

apiVersion: v1
kind: Workflow
metadata:
  name: docker-build
spec:
  requirements:
    tools:
      - name: docker
        version: "20.10"
        description: Docker CLI for building images
    secrets:
      - name: DOCKER_TOKEN
        provider: docker
        required: true
        description: Docker Hub authentication


  jobs:
    - name: build
      steps:
        - name: docker-build
          script: |
            echo "$DOCKER_TOKEN" | docker login -u myuser --password-stdin
            docker build -t myapp:latest .
            docker push myapp:latest

Multi-Tool Deployment

apiVersion: v1
kind: Workflow
metadata:
  name: complete-deploy
spec:
  requirements:
    tools:
      - name: kubectl
        version: "1.28"
      - name: helm
        version: "3.12"
      - name: terraform
        version: "1.5"
    secrets:
      - name: AWS_ACCESS_KEY_ID
        provider: aws
        required: true
      - name: DATADOG_API_KEY
        provider: datadog
        required: false


  jobs:
    - name: infrastructure
      steps:
        - name: terraform-apply
          command: terraform apply -auto-approve


    - name: deploy
      dependsOn: [infrastructure]
      steps:
        - name: helm-install
          command: helm upgrade --install myapp ./chart

Testing Requirements

Test Missing Tools

Terminal window
# Run workflow without helm installed
hyve workflow run k8s-deploy
# Error: Required tool 'helm' not found in PATH

Test Missing Secrets

Terminal window
# Run workflow without setting secrets
hyve workflow run docker-build
# Error: Required secret 'DOCKER_TOKEN' not found

Test With Requirements Met

Terminal window
# Set required secret via environment variable
export DOCKER_TOKEN=your-docker-token


# Run workflow successfully
hyve workflow run docker-build
# ✅ All requirements validated successfully

Workflow Overview

Learn about workflows

Configuration

Configure API tokens and secrets

Workflow Examples

See complete workflow examples

Module System

How modules inject credentials via environment variables