Workflows

Workflows orchestrate multiple block actions in a defined order: concept, workspace.poly definition, execution flow, prompts, allow_failure, practical examples, commands, best practices and troubleshooting.

Workflows

Polycrate supports workflows, i.e. the ordered execution of block actions. A workflow orchestrates multiple block actions in a defined order and thus enables complex deployment and orchestration scenarios.

Workflow concept

graph LR
    WF[Workflow] --> S1[Step 1]
    WF --> S2[Step 2]
    WF --> S3[Step 3]

    S1 --> B1A[Block-1: Action-A]
    S2 --> B2A[Block-2: Action-A]
    S3 --> B1B[Block-1: Action-B]

    B1A --> TX1[Transaction 1]
    B2A --> TX2[Transaction 2]
    B1B --> TX3[Transaction 3]

Key properties:

Workflows are defined in workspace.poly
Each step executes one block action
Steps are executed sequentially
Workflows can contain prompts for confirmation
Failed steps can be tolerated with allow_failure

workspace.poly

name: workflow-workspace

blocks:
  - name: block-1
    actions:
      - name: action-1
        prompt: 
          message: "Do you really want to run this action?"
        playbook: action-1.yml
  - name: block-2
    actions:
      - name: action-1
        playbook: action-1.yml
workflows:
  - name: workflow-1
    prompt: 
          message: "Do you really want to run this workflow?"
    allow_failure: true
    steps:
      - name: block-1-action-1
        block: block-1
        action: action-1
      - name: block-2-action-1
        block: block-2
        action: action-1
        prompt: 
          message: "Do you really want to run this step?"

You can run this workflow with

polycrate workflows run workflow-1

(or, in short, polycrate run workflow-1).

Workflow execution

When you run a workflow, the following sequence takes place:

sequenceDiagram
    participant User
    participant CLI
    participant Step1
    participant Step2
    participant Step3

    User->>CLI: polycrate workflows run workflow-1
    CLI->>CLI: Load workflow definition
    CLI->>CLI: Validate steps

    alt Workflow has prompt
        CLI->>User: Prompt: "Run workflow?"
        User->>CLI: Confirm
    end

    CLI->>Step1: Execute block-1 action-1

    alt Step has prompt
        Step1->>User: Prompt: "Run step?"
        User->>Step1: Confirm
    end

    Step1->>Step1: Execute action

    alt Action successful
        Step1-->>CLI: Success (Exit 0)
        CLI->>Step2: Execute block-2 action-1
        Step2->>Step2: Execute action
        Step2-->>CLI: Success (Exit 0)
        CLI->>Step3: Execute block-3 action-1
        Step3->>Step3: Execute action
        Step3-->>CLI: Success (Exit 0)
        CLI-->>User: Workflow completed successfully
    else Action failed
        Step1-->>CLI: Failure (Exit 1)
        alt allow_failure: true
            CLI->>Step2: Continue to next step
        else allow_failure: false
            CLI-->>User: Workflow aborted
        end
    end

Workflow features

1. Prompts and confirmation

If the workflow, one of its steps or an action contains the prompt key with a non-empty message, Polycrate interrupts the workflow and asks the user for confirmation:

workflows:
  - name: deploy-production
    prompt:
      message: "Deploy to PRODUCTION? This will affect live users!"
    steps:
      - name: backup-database
        block: database
        action: backup
        prompt:
          message: "Create backup before deployment?"

      - name: deploy-app
        block: application
        action: deploy

Skipping prompts:

polycrate workflows run deploy-production --force

2. Error handling with allow_failure

If allow_failure is set to true, execution continues even if individual steps fail:

workflows:
  - name: deploy-with-monitoring
    allow_failure: true
    steps:
      - name: deploy-app
        block: application
        action: deploy
        # This step is critical

      - name: send-notification
        block: monitoring
        action: notify
        # If the notification fails, the workflow still succeeds

3. Resolving dependencies automatically

Workflows can automatically pull block dependencies:

polycrate workflows run deploy-stack --blocks-auto-pull

Practical examples

Example 1: multi-tier application deployment

name: microservices-workspace

blocks:
  - name: infrastructure
    actions:
      - name: provision
        playbook: provision.yml

  - name: database
    from: postgres-base
    actions:
      - name: install
        playbook: install.yml

  - name: backend-api
    from: k8s-app-base
    actions:
      - name: deploy
        playbook: deploy.yml

  - name: frontend
    from: k8s-app-base
    actions:
      - name: deploy
        playbook: deploy.yml

workflows:
  - name: deploy-complete-stack
    prompt:
      message: "Deploy complete microservices stack?"
    steps:
      - name: provision-infrastructure
        block: infrastructure
        action: provision

      - name: deploy-database
        block: database
        action: install

      - name: deploy-backend
        block: backend-api
        action: deploy

      - name: deploy-frontend
        block: frontend
        action: deploy

Execution:

polycrate workflows run deploy-complete-stack --blocks-auto-pull

Example 2: backup and maintenance workflow

workflows:
  - name: maintenance
    allow_failure: true
    steps:
      - name: notify-users
        block: monitoring
        action: send-maintenance-notification

      - name: backup-database
        block: database
        action: backup
        prompt:
          message: "Create database backup?"

      - name: backup-volumes
        block: storage
        action: backup

      - name: update-application
        block: application
        action: update

      - name: verify-health
        block: application
        action: healthcheck

      - name: notify-complete
        block: monitoring
        action: send-complete-notification

Example 3: multi-environment deployment

workflows:
  - name: deploy-to-staging
    steps:
      - name: deploy-staging
        block: application
        action: deploy
        # Block uses the staging kubeconfig

  - name: deploy-to-production
    prompt:
      message: "Deploy to PRODUCTION?"
    steps:
      - name: backup-prod-db
        block: prod-database
        action: backup

      - name: deploy-prod-app
        block: production-application
        action: deploy

      - name: verify-prod
        block: production-application
        action: healthcheck

Workflow commands

Running a workflow

# Full command
polycrate workflows run <workflow-name>

# Short form
polycrate run <workflow-name>

# With auto-pull
polycrate workflows run deploy-stack --blocks-auto-pull

# Without prompts
polycrate workflows run deploy-prod --force

Listing workflows

# All available workflows
polycrate workflows list

# Workflow details
polycrate workflows inspect deploy-stack

Best practices

1. Meaningful step names

# ✅ Good: descriptive names
steps:
  - name: provision-cloud-infrastructure
    block: infrastructure
    action: provision

  - name: deploy-database-cluster
    block: database
    action: install

# ❌ Bad: generic names
steps:
  - name: step1
    block: infrastructure
    action: provision

  - name: step2
    block: database
    action: install

2. Protect critical steps with prompts

workflows:
  - name: destroy-infrastructure
    prompt:
      message: "DANGER: This will destroy all infrastructure. Continue?"
    steps:
      - name: destroy
        block: infrastructure
        action: destroy
        prompt:
          message: "Final confirmation: Really destroy?"

3. Use idempotent actions

Make sure your block actions are idempotent so that workflows can be repeated safely:

# Ansible is idempotent by nature
actions:
  - name: deploy
    playbook: deploy.yml

4. Create rollback workflows

workflows:
  - name: deploy
    steps:
      - name: backup
        block: application
        action: backup
      - name: deploy
        block: application
        action: deploy

  - name: rollback
    steps:
      - name: restore-backup
        block: application
        action: restore
      - name: redeploy-previous
        block: application
        action: deploy-previous-version

5. Monitoring and notifications

workflows:
  - name: deploy-with-monitoring
    allow_failure: true
    steps:
      - name: notify-start
        block: monitoring
        action: notify-deployment-start

      - name: deploy
        block: application
        action: deploy

      - name: verify
        block: application
        action: healthcheck

      - name: notify-complete
        block: monitoring
        action: notify-deployment-complete

Troubleshooting

Workflow fails at a step

There is no workspace folder .logs/ anymore; details on the failed run are found in the terminal output (scrollback) and in the shell history (history), not in a file per transaction.

# 1. Re-run the workflow or use the scrollback: the failed step and message are in the CLI output
polycrate workflows run deploy-stack
# Example: step 'deploy-database' failed — map block/action from workspace.poly

# 2. If needed, more context from the CLI (--loglevel, see global flags)
polycrate --loglevel 2 workflows run deploy-stack

# 3. Reproduce the affected step specifically as an action (block + action from workspace.poly)
polycrate run database install

# 4. Re-run the workflow once the individual fix works
polycrate workflows run deploy-stack

Workflow hangs at a prompt

# Use --force to skip all prompts
polycrate workflows run deploy-stack --force

Changing the step order

Workflows are executed strictly sequentially. To change the order, edit workspace.poly:

workflows:
  - name: deploy
    steps:
      - name: first
        block: block-a
        action: install
      - name: second  # Runs after 'first'
        block: block-b
        action: install

Relation to other concepts

Blocks: workflows orchestrate block actions
Actions: every workflow step executes one action
Dependencies: workflows can resolve dependencies with --blocks-auto-pull