Zigflow starter

A starting point for building, running and validating Zigflow workflows. Extend the included example or replace it with your own.

• About Zigflow
• Project layout
• Run the example
  • Locally
  • With Docker Compose
• Extend the starter
  • Add a workflow
  • Add a trigger
  • Make it your own
• Validate workflows

About Zigflow

Zigflow runs durable Temporal workflows defined in YAML. It provides the worker, so you can focus on your workflow definitions.

See the Zigflow documentation for installation, workflow syntax and concepts.

Project layout

Path	Purpose
workflows/hello-world/workflow.yaml	Example workflow
workflows/hello-world/trigger.sh	Starts the example using the Temporal CLI
Makefile	Local development, validation and trigger commands
compose.yml	Temporal, Zigflow and trigger services
Dockerfile	Zigflow image containing your workflows
.github/workflows/build.yml	Linting, commit-message checks and workflow validation

Run the example

The example uses workflow type hello-world and task queue zigflow. Both options below provide a Temporal UI at http://localhost:8233.

Locally

Install Zigflow and the Temporal CLI. Run these commands in separate terminals, starting the server and worker before triggering the workflow:

make temporal     # Start Temporal
make dev          # Run Zigflow in watch mode
make hello-world  # Execute the example and print its result

With Docker Compose

With Docker Compose installed, run the following commands in separate terminals:

docker compose up zigflow
docker compose run --rm hello-world

The first command starts Temporal and Zigflow. The second executes the example and prints its result. Zigflow watches the mounted workflows/ directory, so workflow edits need no image rebuild.

Extend the starter

Add a workflow

Use one directory per workflow, with its definition named workflow.yaml:

workflows/
  my-workflow/
    workflow.yaml
    trigger.sh

Copy the example into your new directory or start from the Zigflow examples. In the definition's document section, choose:

• workflowType: the name clients use to start the workflow.
• taskQueue: the queue the Zigflow worker polls. Keep zigflow or choose another queue.

make dev and the Compose worker discover workflows recursively and watch for changes.

Every .yaml, .yml and .json file under workflows/ is treated as a workflow definition. Keep supporting files, such as input data and schemas, outside that directory.

Add a trigger

The included trigger.sh demonstrates starting a workflow from the command line. Copy it alongside your definition and update --type and --task-queue to match workflowType and taskQueue.

Optionally add a target under Triggers in the Makefile. For Compose, add a service under services that reuses the existing trigger:

  my-workflow:
    <<: *trigger
    command: sh /workflows/my-workflow/trigger.sh

The anchor supplies the image, Temporal connection settings and workflow mount. Run the trigger with docker compose run --rm my-workflow.

Trigger scripts are optional. Your application can start workflows using a Temporal SDK in its preferred language.

Make it your own

Delete workflows/hello-world/ and its entries in the Makefile and Compose when you no longer need the example. If other services reference *trigger, move the &trigger anchor to a remaining trigger service.

Replace this README with documentation for the workflows you build.

Validate workflows

make validate

This checks every workflow definition without executing workflows or connecting to Temporal. CI validates the same files, with a separate job for each file.

Commit messages follow Conventional Commits.