5.6 KiB

Raw Blame History

OpenHands SDK + n8n Integration Guide

Updated: 2025-12-01 Status: ✅ WORKING - SDK wrapper approach successful

✅ What's Working

Core Components:

OpenHands CLI: /home/bam/.local/bin/openhands (v1.3.0)
SDK Wrapper: /home/bam/openhands-sdk-wrapper-sh.sh (sh-compatible)
n8n Workflow: "OpenHands SDK Clean Working" (ID: 9cgyx4hHEvGjyEaE)
SSH Authentication: Working (permissions fixed)
File Verification: Working (workflow confirms creation)

Key Files:

/home/bam/openhands-sdk-wrapper-sh.sh  # Main wrapper script (sh-compatible)
/home/bam/OPENHANDS_N8N_WORKING.json   # Working n8n workflow template
/home/bam/openhands/.env               # API keys (MiniMax, DeepSeek)
/home/bam/.ssh/                        # SSH credentials (fixed permissions)

🎯 Next Steps: Gitea Webhook Integration

Step 1: Create Gitea Repository & Webhook

In Gitea (https://git.oky.sh):

Create Test Repository:

# Or via web UI: New Repository → "test-project"

Add Webhook:
- Settings → Webhooks → Add Webhook → Gitea
- URL: https://n8n.oky.sh/webhook/gitea-push
- Method: POST
- Content Type: application/json
- Secret: [generate random string]
- Trigger: Push events
- Active: ✓

Step 2: Update n8n Workflow for Webhook

Current Workflow: Manual Trigger → OpenHands SDK → Verify

New Workflow Design:

[1] Webhook Trigger (Gitea push)
     ↓
[2] JSON Parser - Extract repo info
     ↓
[3] SSH - Clone repository
     → git clone https://git.oky.sh/user/repo.git /home/bam/workspace/repo
     ↓
[4] SSH - Execute OpenHands SDK
     → sh /home/bam/openhands-sdk-wrapper-sh.sh "Build and test project {{ $json.repository.name }}"
     ↓
[5] SSH - Verify build artifacts
     → Check for dist/, build/, or test results
     ↓
[6] HTTP - Update Gitea commit status
     → POST /api/v1/repos/{owner}/{repo}/statuses/{sha}

Step 3: n8n Webhook Node Configuration

Node 1: Webhook Trigger

{
  "path": "gitea-push",
  "httpMethod": "POST",
  "responseMode": "responseNode"
}

Node 2: Extract Data (Set Node)

{
  "repository": "{{ $json.repository.full_name }}",
  "clone_url": "{{ $json.repository.clone_url }}",
  "commit": "{{ $json.after }}",
  "branch": "{{ $json.ref }}"
}

Node 3: Clone Repo (SSH Node)

cd /home/bam/workspace
if [ -d "{{ $json.repository.name }}" ]; then
  cd {{ $json.repository.name }} && git pull
else
  git clone {{ $json.clone_url }}
fi

Node 4: Execute OpenHands (SSH Node)

sh /home/bam/openhands-sdk-wrapper-sh.sh \
  "Navigate to /home/bam/workspace/{{ $json.repository.name }} and run: npm install && npm test && npm build. Report any errors."

Node 5: Verify Success (SSH Node)

cd /home/bam/workspace/{{ $json.repository.name }}
if [ -d "dist" ] || [ -f "build/index.html" ]; then
  echo "BUILD_SUCCESS"
else
  echo "BUILD_FAILED"
fi

Node 6: Update Gitea (HTTP Request)

{
  "url": "https://git.oky.sh/api/v1/repos/{{ $json.repository }}/statuses/{{ $json.commit }}",
  "method": "POST",
  "headers": {
    "Authorization": "token YOUR_GITEA_TOKEN",
    "Content-Type": "application/json"
  },
  "body": {
    "state": "success",
    "description": "Build passed - OpenHands SDK",
    "context": "openhands/build"
  }
}

🧪 Testing Workflow

Test 1: Manual Webhook Test

# In Gitea webhook settings, click "Test Delivery"
# Should trigger n8n workflow

Test 2: Git Push Test

cd /home/bam/workspace/test-project
echo "Test" > README.md
git add .
git commit -m "Test webhook trigger"
git push origin main

# Check n8n execution at: https://n8n.oky.sh
# Verify OpenHands SDK executed
# Check Gitea commit status updated

Test 3: Build Failure Test

# Add intentional error to code
git commit -am "Introduce syntax error" && git push

# Verify:
# - n8n workflow runs
# - OpenHands SDK detects error
# - Gitea commit status shows "failure"

📋 Node Configuration Details

SSH Nodes (Repeat for each):

Credential: SSH Private Key account
Authentication: privateKey
Host: localhost
User: bam

Environment Variables:

# Loaded by wrapper script from /home/bam/openhands/.env:
MINIMAX_API_KEY=xxx      # Primary LLM
DEEPSEEK_API_KEY=xxx     # Fallback LLM

✅ Success Criteria

Integration Complete When:

✅ Git push triggers n8n workflow
✅ n8n clones repository
✅ OpenHands SDK executes build/test
✅ Workflow returns success/failure
✅ Gitea commit status updated
✅ End-to-end: Push → Build → Status Update

🔧 Troubleshooting

SSH Authentication Fails:

# Check ownership
sudo chown -R bam:bam /home/bam /home/bam/.ssh
sudo chmod 755 /home/bam

Webhook Not Triggering:

# Check n8n webhook URL
curl https://n8n.oky.sh/webhook/gitea-push

# Check Gitea webhook logs
# Repository → Settings → Webhooks → Recent Deliveries

OpenHands SDK Hangs:

# Wrapper script should handle this
# Check /tmp/software-agent-sdk/ logs
tail -f /tmp/software-agent-sdk/logs/*.log

📚 Quick Reference

Workflow ID:

Production: 9cgyx4hHEvGjyEaE (OpenHands SDK Clean Working)

Wrapper Usage:

sh /home/bam/openhands-sdk-wrapper-sh.sh "Your task description here"

Test Workflow:

# In n8n UI: https://n8n.oky.sh
# Click "OpenHands SDK Clean Working"
# Click "Execute Workflow"

Current Status: Ready to proceed with Gitea webhook integration Next Action: Create test repository and configure webhook

5.6 KiB Raw Blame History