Build Your First Workflow (15 Minutes)

Create a multi-agent workflow that automates code review using BuildKit.

What You'll Build

A CI/CD workflow that:

Validates code quality (Governor agent)
Runs tests (Worker agent)
Posts results to GitLab (Worker agent)

Prerequisites

Completed Platform Setup
BuildKit CLI installed
GitLab account with API access

Step 1: Create Workflow Directory (30 seconds)

mkdir -p ~/Sites/LLM/workflows/code-review-workflow
cd ~/Sites/LLM/workflows/code-review-workflow

Step 2: Create Workflow Manifest (3 minutes)

Create workflow.yaml:

ossaVersion: "0.4.9"

workflow:
  id: code-review-workflow
  name: Code Review Workflow
  version: "1.0.0"
  description: Automated code quality and testing

  trigger:
    type: webhook
    event: gitlab.push

  variables:
    CHANGED_FILES: "{{ event.commits[*].added + event.commits[*].modified }}"
    PROJECT: "{{ event.project.path_with_namespace }}"

  stages:
    # Stage 1: Validate code quality
    - name: validate
      steps:
        - name: check_quality
          agent: code-quality-governor
          capability: validate_code
          input:
            files: "{{ CHANGED_FILES }}"
          output:
            result: validation_result
          on_failure: fail_workflow

    # Stage 2: Run tests
    - name: test
      depends_on: [validate]
      steps:
        - name: run_tests
          agent: test-runner
          capability: run_tests
          input:
            test_suite: unit
          output:
            results: test_results
          on_failure: fail_workflow

    # Stage 3: Post results to GitLab
    - name: report
      depends_on: [test]
      steps:
        - name: post_comment
          agent: gitlab-commenter
          capability: post_comment
          input:
            project: "{{ PROJECT }}"
            commit: "{{ event.checkout_sha }}"
            message: |
              ## Code Review Results

               Code Quality: {{ validation_result.violations | length }} violations
               Tests: {{ test_results.passed }}/{{ test_results.total }} passed

  observability:
    logging:
      level: info
    metrics:
      enabled: true

Step 3: Validate Workflow (30 seconds)

# Validate syntax
buildkit workflows validate workflow.yaml

# Expected output:
#  Workflow syntax valid
#  All referenced agents exist
#  Variable references valid

Step 4: Create Mock Agents (5 minutes)

Since we only have code-quality-governor, let's create mock agents for testing:

Create mock-test-runner.ts:

import express from 'express';

const app = express();
app.use(express.json());

app.get('/health', (req, res) => {
  res.json({ status: 'ok' });
});

app.post('/capabilities/run_tests', (req, res) => {
  res.json({
    passed: 42,
    total: 42,
    duration: 5.2,
    coverage: 85
  });
});

app.listen(3001, () => console.log('Test runner on port 3001'));

Create mock-gitlab-commenter.ts:

import express from 'express';

const app = express();
app.use(express.json());

app.get('/health', (req, res) => {
  res.json({ status: 'ok' });
});

app.post('/capabilities/post_comment', (req, res) => {
  console.log('Would post comment:', req.body.message);
  res.json({ posted: true, comment_id: 123 });
});

app.listen(3002, () => console.log('GitLab commenter on port 3002'));

Start mock agents:

# Terminal 1
npx ts-node mock-test-runner.ts

# Terminal 2
npx ts-node mock-gitlab-commenter.ts

# Terminal 3 (keep code-quality-governor running)
cd ~/Sites/LLM/my-agents/code-quality-governor
npm start

Step 5: Register Mock Agents (2 minutes)

Create test-runner.ossa.yaml:

ossaVersion: "0.4.9"
agent:
  id: test-runner
  name: Test Runner
  version: "1.0.0"
  role: worker
  runtime:
    type: local
    node: { version: "20.x", entrypoint: "mock-test-runner.ts" }
  capabilities:
    - name: run_tests
      description: Run test suite
      input_schema: { type: object }
      output_schema: { type: object }

Create gitlab-commenter.ossa.yaml:

ossaVersion: "0.4.9"
agent:
  id: gitlab-commenter
  name: GitLab Commenter
  version: "1.0.0"
  role: worker
  runtime:
    type: local
    node: { version: "20.x", entrypoint: "mock-gitlab-commenter.ts" }
  capabilities:
    - name: post_comment
      description: Post comment to GitLab
      input_schema: { type: object }
      output_schema: { type: object }

buildkit agents register --manifest test-runner.ossa.yaml --local --port 3001
buildkit agents register --manifest gitlab-commenter.ossa.yaml --local --port 3002

Step 6: Test Workflow Locally (2 minutes)

Create test event (test-event.json):

{
  "event_name": "push",
  "project": {
    "path_with_namespace": "llm/test-project"
  },
  "checkout_sha": "abc123",
  "commits": [
    {
      "added": ["src/new-file.ts"],
      "modified": ["src/index.ts"]
    }
  ]
}

Run workflow:

buildkit workflows run code-review-workflow \
  --local \
  --event-file test-event.json

# Watch execution
buildkit workflows watch code-review-workflow

Expected output:

Stage: validate [RUNNING]
   check_quality [PASSED]  code-quality-governor

Stage: test [RUNNING]
   run_tests [PASSED]  test-runner

Stage: report [RUNNING]
   post_comment [PASSED]  gitlab-commenter

Workflow: code-review-workflow [SUCCESS]
Duration: 2.4s

Step 7: View Results (1 minute)

# Get execution ID
EXEC_ID=$(buildkit workflows executions list --workflow code-review-workflow --limit 1 --format json | jq -r '.[0].id')

# View logs
buildkit workflows executions logs $EXEC_ID

# Get execution summary
buildkit workflows executions status $EXEC_ID --detailed

Step 8: Deploy Workflow (1 minute)

# Register workflow for production
buildkit workflows register workflow.yaml

# Configure GitLab webhook
buildkit gitlab webhooks create \
  --project llm/test-project \
  --workflow code-review-workflow \
  --events push

# Workflow now triggers automatically on Git push!

Test End-to-End

# Make a change in your project
cd ~/Sites/LLM/test-project
echo "console.log('test')" > test.js
git add test.js
git commit -m "test: trigger workflow"
git push

# Watch workflow execute
buildkit workflows watch code-review-workflow

What's Next?

Deploy to Kubernetes: Deploy to K8s
Advanced workflows: Your First Workflow Guide
Production deployment: Production Deployment Guide

Troubleshooting

Workflow not triggering:

# Check webhook configuration
buildkit gitlab webhooks list --project llm/test-project

# Test webhook manually
buildkit gitlab webhooks test <webhook-id>

Agent not responding:

# Check agent status
buildkit agents status test-runner

# View logs
buildkit agents logs test-runner

Time to complete: 15 minutes Next: Deploy to Kubernetes