Your First Workflow

In this guide, you'll build a simple workflow that monitors code commits, analyzes them for issues, and automatically creates fix proposals. By the end, you'll understand the complete event flow from trigger to execution.

Prerequisites

MESH OS CLI installed (npm install -g @mesh-os/cli)
A MESH OS project initialized (mesh init my-project)
Basic understanding of JSON or YAML

Don't have MESH OS installed? Check out the Installation Guide first.

Step 1: Define Your Event

Every workflow starts with an event. Create a file events/code-commit.json:

events/code-commit.json

{
"type": "code.commit.detected",
"source": "github.webhook",
"data": {
  "repository": "my-app",
  "commit": "abc123",
  "files": ["src/services/api.ts"],
  "author": "dev@example.com"
}
}

This event represents a new code commit that needs analysis.

Step 2: Create the Workflow

Create workflows/code-analysis.yaml:

workflows/code-analysis.yaml

name: Code Analysis Pipeline
description: Automatically analyze commits and propose fixes

triggers:
- code.commit.detected

steps:
- module: meshOS
  action: analyze_code
  outputEvent: code.analyzed
  config:
    checks:
      - null-pointers
      - unused-variables
      - security-issues

- module: meshOS
  action: score_issues
  outputEvent: code.scored

- module: meshOS
  action: propose_fixes
  outputEvent: fix.proposed
  condition: score < 80

- module: meshOS
  action: create_pr
  outputEvent: pr.created
  condition: fix.proposed

Understanding the Steps

analyze_code: Scans the committed files for issues
score_issues: Assigns a quality score (0-100)
propose_fixes: Generates fix suggestions if score < 80
create_pr: Opens a pull request with the fixes

Pro Tip

Use conditions to create branching logic. Steps with unmet conditions are skipped but still logged in the audit trail.

Step 3: Add Policies

Create policies/code-analysis.yaml to add governance:

policies/code-analysis.yaml

name: Code Analysis Policies

rules:
- name: Require approval for production
  condition: repository == "production"
  action: require_approval
  approvers:
    - dev-lead@example.com
    - cto@example.com

- name: Block critical security issues
  condition: has_security_issue && severity == "critical"
  action: block
  notify:
    - security@example.com

Policies act as guardrails, preventing risky operations from executing without approval.

Step 4: Deploy the Workflow

Deploy your workflow to MESH OS:

mesh deploy workflows/code-analysis.yaml

# Output:
# ✓ Workflow validated
# ✓ Policy checks passed
# ✓ Deployed to MESH OS
# Workflow ID: wf_abc123

Step 5: Test It

Trigger the workflow manually to test:

mesh trigger code.commit.detected --data '{"repository":"my-app","commit":"abc123"}'

# Output:
# ✓ Event published to spine
# ✓ Workflow matched: Code Analysis Pipeline
# ✓ Execution started
# View logs: mesh logs wf_abc123

Step 6: Monitor Execution

Watch the workflow execute in real-time:

mesh logs wf_abc123 --follow

# Output:
# [10:30:01] code.commit.detected received
# [10:30:02] meshOS.analyze_code started
# [10:30:05] meshOS.analyze_code completed
# [10:30:05] code.analyzed emitted
# [10:30:06] meshOS.score_issues completed
# [10:30:06] Score: 72 (below threshold)
# [10:30:07] meshOS.propose_fixes started
# [10:30:10] fix.proposed emitted
# [10:30:11] meshOS.create_pr completed
# [10:30:11] pr.created: https://github.com/my-app/pull/42

Success!

Your workflow is now live and monitoring commits. Every execution is logged, scored, and governed automatically.

Visualize in the Dashboard

Head to your MESH OS dashboard to see the event flow visualized:

mesh open dashboard

You'll see a timeline of all events, step durations, and any policy checks that were applied.

Next Steps

Now that you've built your first workflow, try:

Integrate an app with MESH OS
Run Spider for automated data collection
Run Axis for sales automation
Explore the Events API for advanced use cases

Troubleshooting

Workflow not triggering? Check that your event type exactly matches the trigger: code.commit.detected

Steps getting skipped? Review your conditions. Use mesh logs --debug to see condition evaluation.

Policy blocking execution? Check policies/ for rules that might be blocking. Use mesh policies list to see active policies.