OwlFlow is a lightweight, high-performance, and extensible workflow automation engine written in Go. It enables event-driven and scheduled workflow execution with declarative YAML/JSON configurations, dynamic templating, conditional branching, and modular connectors.
Try the OwlFlow Studio Live Playground directly in your browser.
Live Studio • Roadmap • Documentation • Ask DeepWiki
- ⚡ Declarative Workflows: Define complex workflows, step transitions, and error handling in clean YAML or JSON.
- 🔀 Conditional Branching & DAG Execution: Execute steps sequentially, conditionally, or in parallel branches based on dynamic step outputs.
- ⏰ Flexible Triggers:
- Webhooks: REST endpoints supporting payload parsing (
JSON,form-data), header inspection, and secret validation (GitLab token & GitHub HMAC SHA-256 signatures). - Cron Schedules: Sub-minute and second-precision scheduling with optional timezone support.
- Webhooks: REST endpoints supporting payload parsing (
- 🔌 Extensible Connectors: Built-in connectors for HTTP, GitLab, Jira, Logger, and Internal Data Processing, with an interface to easily register custom connectors.
- 📝 Powerful Templating Engine: Evaluate dynamic parameters and condition expressions using Go templating with built-in helpers (
toJson,toPrettyJson,first,index,hasPrefix,regexMatch,matches). - 🖥️ Developer Studio & Visualizer: Interactive web UI (React + Vite + Tailwind) hosted on GitHub Pages with real-time YAML validation, interactive DAG flowcharts, built-in Component Guide & Cheat Sheet, and client-side dry-run simulation.
- ☁️ Cloud Native & Serverless Ready: Runs seamlessly as a standalone microservice, Docker container, or AWS Lambda function (via AWS Lambda Web Adapter).
┌────────────────────────┐
│ Trigger / Ingestion │
└───────────┬────────────┘
│
┌──────────────────┴──────────────────┐
▼ ▼
┌─────────────────────┐ ┌─────────────────────┐
│ Webhook Ingress │ │ Cron Scheduler │
│ (Gin REST Server) │ │ (robfig/cron) │
└──────────┬──────────┘ └──────────┬──────────┘
│ │
└──────────────────┬──────────────────┘
│
▼
┌────────────────────────┐
│ Execution Engine │
│ - Parameter Resolution │
│ - Condition Evaluator │
│ - Retry & Error Handle │
└───────────┬────────────┘
│
┌──────────────────────┼──────────────────────┐
▼ ▼ ▼
┌──────────────┐ ┌──────────────┐ ┌──────────────┐
│ HTTP │ │ GitLab │ │ Jira │
│ Connector │ │ Connector │ │ Connector │
└──────────────┘ └──────────────┘ └──────────────┘
│ │ │
▼ ▼ ▼
┌──────────────┐ ┌──────────────┐ ┌──────────────┐
│ Logger │ │ Internal │ │ Custom │
│ Connector │ │ Data Filters │ │ Connectors │
└──────────────┘ └──────────────┘ └──────────────┘
owlflow/
├── cmd/
│ └── server/
│ └── main.go # Application entrypoint & scheduler boot
├── configs/
│ └── workflows/ # Declarative workflow definitions (.yaml / .json)
│ ├── github-monitor.yaml
│ ├── gitlab-monitor.yaml
│ ├── schedule_test.yaml
│ └── test-workflow.yaml
├── docs/ # Detailed documentation and guides
│ ├── overview.md # Architecture and execution lifecycle
│ ├── getting-started.md # Quickstart and setup tutorial
│ ├── configuration.md # Workflow syntax and schema reference
│ ├── connectors.md # Built-in connectors reference & custom connectors
│ ├── templating-and-conditions.md # Templating helpers & condition expressions
│ ├── deployment.md # Docker, AWS (Lambda/ECS), and CloudFormation deployment guide
│ └── ui.md # Developer UI and simulator reference
├── internal/
│ ├── connectors/ # Connector implementations
│ │ ├── base.go # Connector interface and registry
│ │ ├── gitlab.go # GitLab API actions
│ │ ├── http.go # Generic HTTP client actions
│ │ ├── internal.go # JSON/data extraction & regex utilities
│ │ ├── jira.go # Jira Cloud transitions & search
│ │ └── logger.go # Structured JSON logger
│ ├── core/ # Core execution engine
│ │ ├── condition.go # Condition evaluation & parameter resolution
│ │ ├── execution.go # Step execution queue & context management
│ │ ├── scheduler.go # Cron scheduler runner
│ │ ├── template.go # Go template helper functions
│ │ └── workflow.go # Workflow domain models and validation
│ └── server/
│ └── api.go # Gin API routes and webhook security
├── deploy/ # Infrastructure-as-Code deployment templates
│ └── cloudformation/ # AWS CloudFormation templates (Lambda & ECS Fargate)
│ ├── lambda.yaml # Serverless Lambda deployment via AWS Lambda Web Adapter
│ ├── ecs-fargate.yaml # ECS Fargate deployment for continuous daemons
│ └── README.md # CloudFormation parameter references & deployment guide
├── ui/ # Standalone React + Vite + Tailwind Developer UI
│ ├── src/ # UI components, DAG canvas, simulator engine
│ ├── Dockerfile # Dev container with hot reloading
│ └── package.json # Managed with pnpm
├── AGENTS.md # Architecture & guidelines for AI coding agents
├── docker-compose.yaml # Multi-service local setup (Go engine + UI)
├── Dockerfile # Multi-stage container build with Lambda Adapter
├── go.mod
├── go.sum
└── README.md
# Run latest image from GitHub Container Registry
docker run -d \
-p 8080:8080 \
--name owlflow \
-v $(pwd)/configs/workflows:/app/configs/workflows \
ghcr.io/divmora/owlflow:latestDownload the pre-compiled binary for Linux (AMD64/ARM64), macOS (Apple Silicon/Intel), or Windows from GitHub Releases.
# Clone the repository
git clone git@github.com:divmora/owlflow.git
cd owlflow
# Build binary
go build -o owlflow cmd/server/main.go
# Run
./owlflowdocker compose up --build- Backend API:
http://localhost:8080 - Developer UI:
http://localhost:5173
curl -X POST http://localhost:8080/webhook/test-workflow \
-H "Content-Type: application/json" \
-d '{
"event": "ping",
"data": "test_event",
"timestamp": "2026-08-20T12:00:00Z"
}'Here is a sample webhook workflow with conditional branching and Slack alerting:
id: "github-monitor"
name: "GitHub Repository Monitor"
status: "active"
trigger:
type: "webhook"
config:
path: "/github-webhook"
initial_step: "check_commit"
steps:
- id: "check_commit"
action: "http.get"
params:
url: "https://api.github.com/repos/{{ .trigger.payload.repo }}/commits"
next_steps:
- step_id: "notify_slack"
condition: '{{ .steps.check_commit.output.status_code }} != 200'
- step_id: "log_success"
condition: '{{ .steps.check_commit.output.status_code }} == 200'
- id: "notify_slack"
action: "http.post"
params:
url: "https://hooks.slack.com/services/YOUR/WEBHOOK/URL"
headers:
Content-Type: "application/json"
body: '{"text": "GitHub API Error: {{ .steps.check_commit.output.body }}"}'
- id: "log_success"
action: "logger.info"
params:
message: "Successfully verified commits for repo {{ .trigger.payload.repo }}"| Variable | Description | Default |
|---|---|---|
PORT |
Port for the HTTP API server | 8080 |
GITLAB_TOKEN |
Private / Personal Access Token for GitLab API | None |
JIRA_USER |
Jira Cloud username / email | None |
JIRA_TOKEN |
Jira Cloud API token / password | None |
JIRA_BASE_URL |
Base URL for Jira Cloud instance | None |
SYSLOG_ENABLED |
Enable forwarding all logger events to Syslog (true / false) |
false |
SYSLOG_ADDR |
Remote Syslog host and port (e.g. 127.0.0.1:514) |
Local socket |
SYSLOG_NETWORK |
Protocol for remote Syslog (udp or tcp) |
udp |
SYSLOG_TAG |
Program identifier tag in Syslog messages | owlflow |
SYSLOG_ONLY |
When true, suppresses stdout logging and only outputs to Syslog |
false |
AWS_LAMBDA_FUNCTION_NAME |
Set by AWS Lambda runtime (activates synchronous execution mode) | None |
Comprehensive guides and references are available in the docs/ directory:
- 📖 Architecture & Overview: Deep dive into the execution lifecycle, execution context, and design principles.
- 🚀 Getting Started Guide: Step-by-step setup, creating your first workflow, and testing.
- ⚙️ Configuration Guide: Complete YAML schema, triggers, step options, retries, and variables.
- 🔌 Connectors Reference: Details on all built-in actions (
http,gitlab,jira,logger,internal) and how to build custom connectors. - 🔣 Templating & Conditions: Template functions (
toJson,first,index,hasPrefix), context variables, and condition evaluation syntax. - 🖥️ Developer UI & Visualizer: Interactive web UI, real-time validator, DAG flowchart, and dry-run simulator.
- 🐳 Deployment Guide: Running via Docker, Docker Compose, Kubernetes, AWS Lambda (Serverless), ECS Fargate, and CloudFormation.
- ☁️ CloudFormation Templates: Production-ready AWS IaC templates for Lambda and ECS Fargate deployments with full parameter references.
- 🤖 Agent Guidelines: Architecture, coding conventions, testing procedures, and guidelines for AI coding agents.
OwlFlow provides standardized build and testing automation via make:
# Compile server binary into bin/owlflow
make build
# Run Go unit test suite with race detector
make test
# Generate HTML code coverage report
make test-coverage
# Format Go source code and run static analysis
make fmt
make lint
# Lint CloudFormation templates (requires cfn-lint)
make cfn-lint
# Run UI tests and build production assets
make ui-test
make ui-build
# Build unified GitHub Pages documentation and Studio bundle
make ui-pages
# Build container image
make docker-buildContributions, bug reports, and feature requests are welcome! Please read our community guidelines:
- 📋 Contributing Guide: Local setup, Conventional Commits, and pull request checklist.
- 📜 Code of Conduct: Standards for a welcoming and respectful community.
- 🔒 Security Policy: Vulnerability disclosure procedure and 48-hour response SLA.
This project is open-source software licensed under the Apache License, Version 2.0.
- Free & Unrestricted Use: Permitted for free use, reproduction, modification, distribution, and execution in any environment (including commercial, enterprise production, SaaS, private, and homelab environments) without requiring any commercial license (EULA) or payment.
- Patent Grant & Protection: Includes standard Apache 2.0 perpetual patent license grants and liability disclaimers.
See LICENSE for full terms.