Core Concept

Workflows

Workflows are JSON files that define a series of steps to execute, their dependencies, and configurations.

Structure

A workflow consists of a name, optional inputs, and an array of steps.

json

{
  "name": "my-workflow",
  "description": "Optional description",
  "inputs": {
    "param1": "default_value",
    "param2": "{{env.ENV_VAR}}"
  },
  "steps": [
    {
      "id": "step1",
      "type": "module.type",
      "config": {},
      "depends_on": []
    }
  ]
}

Step Properties

Property	Required	Description
id	Yes	Unique identifier for the step
type	Yes	Module type (e.g., print, slack.notify)
config	Yes	Module-specific configuration object
depends_on	No	Array of step IDs this step depends on
pause	No	Pause workflow after this step (for approvals)

Complete Example

json

{
  "name": "deploy-pipeline",
  "description": "Build, test, and deploy application",
  "inputs": {
    "environment": "staging",
    "version": "{{env.COMMIT_SHA}}"
  },
  "steps": [
    {
      "id": "checkout",
      "type": "git.diff",
      "config": {
        "operation": "diff"
      }
    },
    {
      "id": "build",
      "type": "shell",
      "config": {
        "command": "docker build -t app:{{inputs.version}} ."
      },
      "depends_on": ["checkout"]
    },
    {
      "id": "test",
      "type": "shell",
      "config": {
        "command": "npm test"
      },
      "depends_on": ["build"]
    },
    {
      "id": "deploy",
      "type": "shell",
      "config": {
        "command": "kubectl apply -f k8s/"
      },
      "depends_on": ["test"]
    },
    {
      "id": "notify",
      "type": "slack.notify",
      "config": {
        "webhook_url": "{{env.SLACK_WEBHOOK}}",
        "message": "Deployed {{inputs.version}} to {{inputs.environment}}"
      },
      "depends_on": ["deploy"]
    }
  ]
}

Best Practices

• Use descriptive step IDs (kebab-case or snake_case)
• Keep workflows focused on a single purpose
• Use inputs for values that change between runs
• Define dependencies explicitly rather than relying on step order
• Store workflows in version control