​
Repository Structure

Your workflow repository can be organized in any way you prefer. Here’s a simple example:

my-workflow/
├── manifest.yaml      # Workflow metadata and configuration
├── README.md         # Documentation
├── src/              # Source directory (optional)
│   ├── workflow.yaml # Main workflow file
│   ├── tasks/        # Reusable task definitions
│   │   ├── data.yaml
│   │   └── notify.yaml
│   └── utils.yaml    # Additional workflow definitions
└── env.example      # Example environment variables

​
Manifest File

The manifest.yaml defines your workflow’s metadata, dependencies, and configuration:

type: workflow
name: data-processor
version: 1.0.0
license: MIT
description: Workflow for processing and analyzing data streams
repository: https://github.com/your-org/data-processor
main: src/workflow.yaml  # Path to the main workflow file

tags:
  - data
  - processing
  - analytics

author:
  name: Your Name
  email: your.email@example.com
  organization: Your Organization

# Dependencies
dependencies:
  tasks:
    - compozy/tasks:data-transform@1.0.0
    - compozy/tasks:notification@1.0.0
  tools:
    - compozy/tools:api-client@1.0.0

# Default workflow configuration
config:
  max_concurrent: 3
  retry_policy:
    max_attempts: 3
    backoff: exponential
    initial_interval: 1s

​
Workflow Definition

The main workflow file defines the actual workflow logic. This can be placed anywhere in your repository, just make sure to reference it in the main property of your manifest:

name: data-processing-workflow
version: 1.0.0
description: Process and analyze data streams

# Environment variables
env:
  API_KEY: "{{ EXTERNAL_API_KEY }}"
  BATCH_SIZE: "{{ input.batch_size }}"

# Trigger configuration
trigger:
  type: webhook
  config:
    url: "/process-data"
    method: POST

# Task definitions
tasks:
  - id: fetch_data
    type: basic
    use: compozy/tools:api-client@1.0.0
    with:
      url: "{{ input.data_source }}"
      format: "{{ input.format }}"
    retry:
      attempts: 3
      backoff: exponential
      interval: 1s
    on_success:
      next: transform_data
    on_error:
      next: handle_error

  - id: transform_data
    type: basic
    use: compozy/tasks:data-transform@1.0.0
    with:
      data: "{{ tasks.fetch_data.output }}"
      batch_size: "{{ env.BATCH_SIZE }}"
    on_success:
      next: process_batches

  - id: process_batches
    type: parallel
    config:
      max_concurrent: "{{ config.max_concurrent }}"
      fail_fast: false
    execute:
      - use: compozy/tasks:batch-processor@1.0.0
        with:
          data: "{{ tasks.transform_data.output }}"
    on_complete:
      next: send_notification

  - id: send_notification
    type: basic
    use: compozy/tasks:notification@1.0.0
    with:
      message: "Data processing complete"
      data: "{{ tasks.process_batches.output }}"

  - id: handle_error
    type: basic
    use: compozy/tasks:error-handler@1.0.0
    with:
      error: "{{ error }}"

​
Component Imports

As any other component, shared workflows can import and use various components from other files or packages:

tasks:
  - id: process_data
    import: ./tasks/data.yaml
    with:
      data: "{{ trigger.data }}"

You can reference:

and all other components we have predefined on Compozy.

​
Publishing

To publish your workflow to the Compozy registry:

1

Prepare Your Repository

  • Initialize a GitHub repository
  • Set up CI/CD workflows
  • Include comprehensive documentation in README.md
2

Validate

Ensure your workflow configuration is valid:

compozy workflow validate
3

Version and Release

  • Use semantic versioning (MAJOR.MINOR.PATCH)
  • Create GitHub releases with detailed changelogs
  • Tag releases (e.g., v1.0.0)
4

Submit to Registry

Once your workflow is ready for distribution:

# Login to Compozy CLI
compozy login

# Submit your workflow
compozy publish

After submission, our team will review your workflow to ensure it meets our quality and security standards. You’ll receive notifications about the review process and when your workflow is approved and listed in the registry.

Make sure your workflow follows these best practices:

  • Use semantic versioning for your workflow versions
  • Include comprehensive documentation in README.md
  • Test your workflow thoroughly before publishing
  • Use environment variables for sensitive configuration
  • Implement proper error handling and retry policies