mvp-factory-openhands/PHASE3_ENHANCED_WORKFLOW.md

# Phase 3: Enhanced CI/CD Workflow

**Status:** ✅ Imported to n8n  
**Webhook URL:** `https://n8n.oky.sh/webhook/openhands-enhanced`  
**Last Updated:** 2025-12-01

---

## 🎯 **Enhanced Features**

### 1. **Retry Logic**
- Maximum 3 retry attempts
- 15-second wait between retries
- Tracks retry count in workflow static data

### 2. **Status Checking**
- Waits 10 seconds for OpenHands initialization
- Simulates build status checking
- Returns SUCCESS/FAILED status

### 3. **Response Formatting**
- JSON response with emoji indicators
- Includes retry count
- Shows build status, repo, branch, commit

### 4. **Error Handling**
- Graceful degradation
- Clear error messages
- Fallback responses

---

## 🔄 **Workflow Flow**

```
[1] Gitea Webhook
     ↓
[2] Extract Repo Info (JavaScript)
     ↓
[3] Start OpenHands Build (SSH)
     ↓
[4] Wait 10s (Initialization)
     ↓
[5] Check Build Status (Simulated)
     ↓
[6] Should Retry? (IF Node)
     ├─ NO → [7] Format Response
     └─ YES → [8] Wait 15s → [9] Under Max Retries?
              ├─ YES → [10] Increment Retry → [11] Retry Build
              └─ NO → [7] Format Response (MAX EXCEEDED)
     ↓
[7] Format Response (with emoji & details)
     ↓
[8] Send JSON Response
```

---

## 📊 **Response Format**

### Success Response
```json
{
  "status": "SUCCESS",
  "emoji": "✅",
  "repo": "gitadmin/mvp-factory-openhands",
  "branch": "main",
  "commit": "abc123",
  "message": "Build completed successfully",
  "timestamp": "2025-12-01T18:15:00.000Z",
  "retry_count": 0
}
```

### Failure Response
```json
{
  "status": "FAILED",
  "emoji": "❌",
  "repo": "gitadmin/mvp-factory-openhands",
  "branch": "main",
  "commit": "abc123",
  "message": "Build failed - errors detected",
  "timestamp": "2025-12-01T18:15:00.000Z",
  "retry_count": 1
}
```

---

## 🔧 **Key Improvements Over Phase 2**

### Phase 2 (Basic)
- Webhook → Extract → SSH → Response
- Simple execution
- No retry logic
- No status checking
- Basic response

### Phase 3 (Enhanced)
- ✅ Webhook → Extract → SSH → Wait → Check → Retry Loop → Response
- ✅ Retry logic (3 attempts)
- ✅ Status checking
- ✅ Detailed response with status
- ✅ Error handling
- ✅ Better UX with emojis

---

## 🧪 **Testing**

### Activate Workflow
1. Go to: https://n8n.oky.sh
2. Find: "Gitea → OpenHands Enhanced CI/CD"
3. **Toggle to activate** (green)

### Test Manually
```bash
curl -X POST https://n8n.oky.sh/webhook/openhands-enhanced \
  -H "Content-Type: application/json" \
  -d '{
    "repository": {
      "name": "test-repo",
      "full_name": "gitadmin/test-repo",
      "clone_url": "https://git.oky.sh/gitadmin/test-repo.git"
    },
    "ref": "refs/heads/main",
    "after": "xyz789",
    "commits": [{"message": "Test enhanced workflow"}],
    "pusher": {"username": "gitadmin"}
  }'
```

### Expected Response
```json
{
  "status": "SUCCESS",
  "emoji": "✅",
  "message": "Build completed successfully",
  ...
}
```

---

## 🚀 **Gitea Webhook Configuration**

### Update Gitea Webhook
1. Go to Gitea repository
2. Settings → Webhooks → Edit existing webhook
3. Update URL to: `https://n8n.oky.sh/webhook/openhands-enhanced`
4. Save

### Alternative: Create New Webhook
1. Add Webhook → Gitea
2. URL: `https://n8n.oky.sh/webhook/openhands-enhanced`
3. Push Events: ✅
4. Active: ✅

---

## 📈 **Production Readiness**

### ✅ Working
- Webhook receiving
- Payload extraction
- SSH execution
- Retry logic
- Status reporting
- Response formatting

### 🔄 Future Enhancements
- Actual OpenHands status checking (instead of simulation)
- Post status to Gitea API (commit statuses)
- Email/Slack notifications
- Build artifacts storage
- Test result reporting

---

## 🔑 **Configuration**

### Workflow Settings
- **Name:** "Gitea → OpenHands Enhanced CI/CD"
- **Path:** `openhands-enhanced`
- **Active:** ✅
- **Version:** 1

### SSH Credentials
- **ID:** v2BMXeCFGpXaoIyb
- **Name:** SSH Private Key account
- **Key:** /home/bam/.ssh/n8n_key

### Retry Settings
- **Max Retries:** 3
- **Wait Between Retries:** 15 seconds
- **Initial Wait:** 10 seconds

---

## 📝 **Notes**

- This workflow is **simulated** - build status checking is mocked
- In production, replace "Check Build Status" with actual OpenHands API polling
- Retry logic uses n8n static data to persist counter across nodes
- The workflow will eventually complete (either SUCCESS or MAX RETRIES EXCEEDED)

---

## 🎓 **Key Learnings**

1. **n8n Static Data** - Use `$workflow.staticData` for persistent state
2. **Retry Patterns** - Combine Wait + IF nodes for retry loops
3. **Response Formatting** - JavaScript nodes can format JSON responses
4. **Conditional Logic** - IF nodes with multiple branches for complex flows
5. **SSH Integration** - Works reliably for executing commands remotely

---

**Status:** Ready for testing ✅  
**Next:** Configure Gitea webhook and test end-to-end