JABSC logoJABSC

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
1{
2"type": "code.commit.detected",
3"source": "github.webhook",
4"data": {
5  "repository": "my-app",
6  "commit": "abc123",
7  "files": ["src/services/api.ts"],
8  "author": "dev@example.com"
9}
10}

This event represents a new code commit that needs analysis.

Step 2: Create the Workflow

Create workflows/code-analysis.yaml:

workflows/code-analysis.yaml
1name: Code Analysis Pipeline
2description: Automatically analyze commits and propose fixes
3
4triggers:
5- code.commit.detected
6
7steps:
8- module: meshOS
9  action: analyze_code
10  outputEvent: code.analyzed
11  config:
12    checks:
13      - null-pointers
14      - unused-variables
15      - security-issues
16
17- module: meshOS
18  action: score_issues
19  outputEvent: code.scored
20
21- module: meshOS
22  action: propose_fixes
23  outputEvent: fix.proposed
24  condition: score < 80
25
26- module: meshOS
27  action: create_pr
28  outputEvent: pr.created
29  condition: fix.proposed

Understanding the Steps

  1. analyze_code: Scans the committed files for issues
  2. score_issues: Assigns a quality score (0-100)
  3. propose_fixes: Generates fix suggestions if score < 80
  4. 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
1name: Code Analysis Policies
2
3rules:
4- name: Require approval for production
5  condition: repository == "production"
6  action: require_approval
7  approvers:
8    - dev-lead@example.com
9    - cto@example.com
10
11- name: Block critical security issues
12  condition: has_security_issue && severity == "critical"
13  action: block
14  notify:
15    - 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:

1mesh deploy workflows/code-analysis.yaml
2
3# Output:
4# ✓ Workflow validated
5# ✓ Policy checks passed
6# ✓ Deployed to MESH OS
7# Workflow ID: wf_abc123

Step 5: Test It

Trigger the workflow manually to test:

1mesh trigger code.commit.detected --data '{"repository":"my-app","commit":"abc123"}'
2
3# Output:
4# ✓ Event published to spine
5# ✓ Workflow matched: Code Analysis Pipeline
6# ✓ Execution started
7# View logs: mesh logs wf_abc123

Step 6: Monitor Execution

Watch the workflow execute in real-time:

1mesh logs wf_abc123 --follow
2
3# Output:
4# [10:30:01] code.commit.detected received
5# [10:30:02] meshOS.analyze_code started
6# [10:30:05] meshOS.analyze_code completed
7# [10:30:05] code.analyzed emitted
8# [10:30:06] meshOS.score_issues completed
9# [10:30:06] Score: 72 (below threshold)
10# [10:30:07] meshOS.propose_fixes started
11# [10:30:10] fix.proposed emitted
12# [10:30:11] meshOS.create_pr completed
13# [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:

1mesh 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:

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.