10 KiB

Raw Blame History

Gitea → n8n → OpenHands Webhook Integration Guide

Workflow: Automatic CI/CD on every git push File: /tmp/openhands-gitea-webhook-workflow.json

📋 Overview

This workflow automatically triggers OpenHands builds when you push to Gitea:

Git Push → Gitea Webhook → n8n → OpenHands API → Build & Test → Results

🚀 Step-by-Step Setup

Step 1: Import Webhook Workflow to n8n (5 min)

Open https://n8n.oky.sh
Log in with your credentials
Click "Workflows" → "Add Workflow"
Click "⋮" menu → "Import from File"
Upload /tmp/openhands-gitea-webhook-workflow.json
Click "Save"
Give it a name: "Gitea CI/CD with OpenHands"

Step 2: Activate the Workflow

In the workflow editor, find the toggle switch at the top
Click it to change from "Inactive" to "Active"
The workflow is now listening for webhooks!

Step 3: Get the Webhook URL

Click on the "Gitea Webhook" node (first node)
Look for "Webhook URLs" section
Copy the Production URL, it should look like:
```
https://n8n.oky.sh/webhook/gitea-push
```
Keep this URL handy for Gitea configuration

🔧 Gitea Repository Setup

Step 4: Create Test Repository in Gitea (5 min)

Open https://git.oky.sh
Log in with your Gitea credentials
Click "+" (top right) → "New Repository"
Fill in:
- Repository Name: openhands-test
- Description: "Test repo for OpenHands CI/CD"
- Visibility: Private or Public (your choice)
- Initialize Repository: ✓ Check this
- Add .gitignore: Node
- Add README: ✓ Check this
Click "Create Repository"

Step 5: Configure Gitea Webhook (5 min)

In your repository, click "Settings" (gear icon, top right)
Click "Webhooks" in the left sidebar
Click "Add Webhook" → "Gitea"
Configure:

Target URL:

https://n8n.oky.sh/webhook/gitea-push

HTTP Method:

POST

POST Content Type:

application/json

Secret: (Optional, leave empty for now)

Trigger On:

✓ Push Events
✗ Create Events
✗ Delete Events
✗ Fork Events
etc. (uncheck all others)

Branch filter: (leave empty to trigger on all branches)

Active: ✓ Check this!

Click "Add Webhook"

Step 6: Test the Webhook (2 min)

On the webhook page, scroll down to "Recent Deliveries"
Click "Test Delivery" button
You should see a new delivery appear
Click on it to see the response
Expected: HTTP 200 OK

If you get an error, check:

n8n workflow is Active
Webhook URL is correct
n8n is accessible at https://n8n.oky.sh

🧪 Testing End-to-End Automation

Step 7: Clone Repository Locally

# Clone the test repository
git clone https://git.oky.sh/[your-username]/openhands-test.git
cd openhands-test

# Check current status
git status

Step 8: Create a Simple Node.js Project

# Initialize package.json
cat > package.json << 'EOF'
{
  "name": "openhands-test",
  "version": "1.0.0",
  "description": "Test project for OpenHands CI/CD",
  "main": "index.js",
  "scripts": {
    "test": "node test.js",
    "build": "echo 'Build completed successfully'"
  },
  "author": "",
  "license": "MIT"
}
EOF

# Create main file
cat > index.js << 'EOF'
function add(a, b) {
  return a + b;
}

function multiply(a, b) {
  return a * b;
}

module.exports = { add, multiply };
EOF

# Create test file
cat > test.js << 'EOF'
const { add, multiply } = require('./index.js');

console.log('Running tests...');

// Test add function
if (add(2, 3) === 5) {
  console.log('✓ add(2, 3) = 5 PASSED');
} else {
  console.log('✗ add test FAILED');
  process.exit(1);
}

// Test multiply function
if (multiply(4, 5) === 20) {
  console.log('✓ multiply(4, 5) = 20 PASSED');
} else {
  console.log('✗ multiply test FAILED');
  process.exit(1);
}

console.log('\nAll tests passed! ✅');
EOF

# Add all files
git add .
git commit -m "Add Node.js project with tests"
git push origin main

Step 9: Monitor the Workflow

In n8n:

Go to "Executions" (left sidebar)
You should see a new execution appear
Click on it to see the progress
Watch as each node executes:
- ✅ Webhook received
- ✅ Repo info extracted
- ✅ OpenHands session created
- ✅ Build status polled
- ✅ Events retrieved
- ✅ Results analyzed

Expected execution time: 2-3 minutes (first time), 30-60 seconds (subsequent)

In Gitea:

Go to your repository → Settings → Webhooks
Click on your webhook
Scroll to "Recent Deliveries"
You should see the delivery with HTTP 200 response

Step 10: Verify Build Results

Check n8n Execution:

In n8n, click on the execution
Click on "Analyze Build Results" node

Check the output - you should see:

{
  "repo": "username/openhands-test",
  "branch": "main",
  "commit": "abc123...",
  "build_status": "SUCCESS" or "FAILED",
  "total_events": 10+,
  "has_errors": false,
  "has_success": true
}

Check OpenHands Logs:

# List conversations
curl http://localhost:3000/api/conversations | python3 -m json.tool

# Get specific conversation events (use conversation_id from n8n)
curl "http://localhost:3000/api/conversations/[conversation-id]/events" | python3 -m json.tool

Check Runtime Container:

# Find the runtime container
docker ps | grep openhands-runtime

# Check if tests ran successfully
docker exec [container-name] cat /workspace/test.js

# Check installed packages
docker exec [container-name] ls -la /workspace/node_modules

🎯 Workflow Logic Explained

Node 1: Gitea Webhook

Trigger: Receives POST requests from Gitea
Path: /webhook/gitea-push
Payload: Complete webhook payload with repo, commit, pusher info

Node 2: Extract Repo Info

Parses Gitea webhook payload
Extracts: repository name, clone URL, branch, commit SHA, message
Builds task description for OpenHands

Node 3: Create OpenHands Session

POST /api/conversations
Passes repository URL and branch
Includes custom build task

Node 4-8: Status Polling Loop

Waits 10s initially
Checks status every 15s
Max 20 retries (5 minutes timeout)
Loops until status is RUNNING, STOPPED, or AWAITING_USER_INPUT

Node 9: Get Build Events

Retrieves all events from the conversation
Contains logs, actions, observations

Node 10: Analyze Build Results

Scans events for error/success indicators
Determines final build status
Counts total events

Node 11-12: Format & Respond

Formats response JSON
Sends back to Gitea webhook

📊 Customizing the Workflow

Change Build Commands

Edit the "Extract Repo Info" node, modify the task variable:

const task = `Build and test project ${repoFullName}. ` +
             `Run: npm install && npm run lint && npm test && npm build`;

Add Python Support

const task = `Clone repository, install dependencies with pip, ` +
             `and run: pip install -r requirements.txt && pytest`;

Add Docker Build

const task = `Build Docker image: docker build -t ${repoName}:${commitSha.substring(0,8)} . ` +
             `Run tests in container: docker run ${repoName} npm test`;

Filter by Branch

Add a filter after webhook trigger:

// In Extract Repo Info node, add at the top:
const branch = payload.ref?.replace('refs/heads/', '') || '';

if (branch !== 'main' && branch !== 'develop') {
  throw new Error('Skipping build for branch: ' + branch);
}

Add Notifications

After "Analyze Build Results", add:

Slack notification node
Email node
Discord webhook

Example for Slack:

{
  "channel": "#ci-cd",
  "text": "Build {{$json.build_status}} for {{$json.repo}} on {{$json.branch}}"
}

🐛 Troubleshooting

Webhook Not Triggering

Problem: No execution appears in n8n after git push

Solutions:

Check workflow is Active (toggle at top of workflow)
Verify webhook URL in Gitea matches n8n webhook path
Check Gitea "Recent Deliveries" for errors
Test webhook manually in Gitea UI

Debug:

# Check n8n logs
docker logs n8n | grep webhook

# Test webhook manually
curl -X POST https://n8n.oky.sh/webhook/gitea-push \
  -H "Content-Type: application/json" \
  -d '{"test": "data"}'

Build Timeout

Problem: Workflow hits max retries (5 minutes)

Solutions:

Increase max retries in "Retry Counter" node (change maxRetries from 20 to 40)
Increase wait time from 15s to 30s

Check OpenHands logs for errors:

sudo journalctl -u openhands.service -f

Build Always Shows "UNKNOWN"

Problem: Build status is never SUCCESS or FAILED

Solutions:

Check event messages don't contain success/error keywords

Modify "Analyze Build Results" node to look for different patterns:

const hasSuccess = events.some(e =>
  e.message?.includes('Tests passed') ||
  e.message?.includes('Build complete')
);

OpenHands Connection Failed

Problem: "Cannot reach 172.18.0.1:3000"

Solutions:

Verify OpenHands is running:

sudo systemctl status openhands.service
curl http://localhost:3000/api/options/agents

Test from n8n container:

docker exec n8n wget -O- http://172.18.0.1:3000/api/options/agents

Restart n8n:

cd /home/bam/services/services-stack
docker compose restart n8n

🎉 Success Criteria

✅ Git push triggers n8n workflow automatically
✅ n8n creates OpenHands conversation
✅ OpenHands clones repository
✅ OpenHands runs build commands (npm install, test, build)
✅ Build results are analyzed
✅ Webhook response is sent back to Gitea
✅ Execution completes within 5 minutes

🔗 Resources

Webhook Workflow: /tmp/openhands-gitea-webhook-workflow.json
Test Workflow: /tmp/openhands-workflow.json
API Reference: /home/bam/openhands-api-reference.md
Gitea: https://git.oky.sh
n8n: https://n8n.oky.sh
OpenHands API: http://localhost:3000/docs

Ready to go live! 🚀

Push your code and watch the magic happen!

10 KiB Raw Blame History

Gitea → n8n → OpenHands Webhook Integration Guide

📋 Overview

🚀 Step-by-Step Setup

Step 1: Import Webhook Workflow to n8n (5 min)

Step 2: Activate the Workflow

Step 3: Get the Webhook URL

🔧 Gitea Repository Setup

Step 4: Create Test Repository in Gitea (5 min)

Step 5: Configure Gitea Webhook (5 min)

Step 6: Test the Webhook (2 min)

🧪 Testing End-to-End Automation

Step 7: Clone Repository Locally

Step 8: Create a Simple Node.js Project

Step 9: Monitor the Workflow

Step 10: Verify Build Results

🎯 Workflow Logic Explained

Node 1: Gitea Webhook

Node 2: Extract Repo Info

Node 3: Create OpenHands Session

Node 4-8: Status Polling Loop

Node 9: Get Build Events

Node 10: Analyze Build Results

Node 11-12: Format & Respond

📊 Customizing the Workflow

Change Build Commands

Add Python Support

Add Docker Build

Filter by Branch

Add Notifications

🐛 Troubleshooting

Webhook Not Triggering

Build Timeout

Build Always Shows "UNKNOWN"

OpenHands Connection Failed

🎉 Success Criteria

🔗 Resources

10 KiB

Raw Blame History