# Migration Summary: SSH → GitHub Actions

**Date:** 2025-12-02
**Decision:** Adopt hybrid approach (n8n + GitHub Actions)
**Timeline:** 3-4 days
**Status:** Ready to implement

---

## 🎯 Decision Summary

**RECOMMENDATION:** Hybrid Approach (Option A)

**Reasoning:**
1. ✅ **Risk:** Low - builds on working n8n infrastructure
2. ✅ **Benefits:** 40-60% simpler, better error handling, native logging
3. ✅ **Time:** 3-4 days (acceptable for significant improvement)
4. ✅ **Future-proof:** Positions for full GitHub Actions migration later
5. ✅ **Learning:** Team gains Python SDK experience

**Rejected:**
- ❌ **Full GitHub Actions (Option B):** Too complex, requires Gitea Actions support check
- ❌ **Stay SSH (Option C):** Works but technical debt, outdated approach

---

## 📊 Quick Comparison

| Metric | Current (SSH) | New (GitHub Actions) |
|--------|---------------|----------------------|
| **Architecture** | n8n → SSH → CLI | n8n → HTTP → Actions |
| **Complexity** | 11 nodes | 5 nodes |
| **Authentication** | SSH keys | GitHub token |
| **Logging** | Basic | Structured + Artifacts |
| **Retry Logic** | Custom n8n logic | GitHub Actions native |
| **Error Handling** | Manual | Built-in + SDK |
| **Lines of Code** | ~300 | ~150 |
| **Setup Time** | 4-5 hours (done) | 3-4 days (new) |

---

## 📋 Implementation Plan

### Phase 1: GitHub Actions Setup (Day 1)
**Duration:** 2-3 hours

**Tasks:**
- [ ] Create GitHub repository or mirror from Gitea
- [ ] Add workflow file: `.github/workflows/openhands-build.yml`
- [ ] Add agent script: `.github/scripts/agent_build.py`
- [ ] Configure GitHub secrets:
  - `OPENHANDS_API_KEY` (from `/home/bam/openhands/.env`)
  - `GITEA_API_TOKEN` (generate in Gitea)
- [ ] Configure GitHub variables:
  - `LLM_MODEL`: `anthropic/claude-sonnet-4-5-20250929`
  - `GITEA_API_URL`: `https://git.oky.sh`
- [ ] Test manually via GitHub Actions UI
- [ ] Verify logs uploaded as artifacts
- [ ] Verify Gitea status update works

**Success Criteria:**
- GitHub Actions runs successfully
- OpenHands SDK executes build task
- Logs and artifacts captured
- Gitea status updated automatically

### Phase 2: n8n Integration (Day 2)
**Duration:** 3-4 hours

**Tasks:**
- [ ] Update existing workflow (ID: j1MmXaRhDjvkRSLa)
- [ ] Replace SSH node with HTTP node (GitHub Actions trigger)
- [ ] Add HTTP node for GitHub Actions status check
- [ ] Simplify data flow (remove $node pattern complexity)
- [ ] Test n8n → GitHub Actions trigger
- [ ] Test GitHub Actions → n8n callback
- [ ] Verify data preservation works
- [ ] Test with real repository push

**Success Criteria:**
- n8n triggers GitHub Actions successfully
- GitHub Actions reports back to n8n
- Workflow completes end-to-end
- Simpler code (no SSH wrapper)

### Phase 3: Error Handling & Retry (Day 3)
**Duration:** 2-3 hours

**Tasks:**
- [ ] Test failure scenarios
- [ ] Verify retry logic (GitHub Actions can be re-triggered)
- [ ] Test max retries (stop after 3 attempts)
- [ ] Verify error messages are clear
- [ ] Test with intentional build failures
- [ ] Ensure Gitea status updates on failure
- [ ] Test with multiple repositories

**Success Criteria:**
- Build failures detected correctly
- Retry attempts work (max 3)
- Error messages helpful and actionable
- Gitea status reflects actual state

### Phase 4: Documentation & Cleanup (Day 4)
**Duration:** 2-3 hours

**Tasks:**
- [ ] Update `phase3.md` with new approach
- [ ] Document all configuration steps
- [ ] Create troubleshooting guide
- [ ] Archive old SSH approach files
- [ ] Test with production project
- [ ] Verify all scenarios work
- [ ] Update project README
- [ ] Create migration checklist

**Success Criteria:**
- Complete documentation
- Production-ready system
- All tests passing
- Clean codebase

---

## 📁 Files Created

### New Files
- ✅ `/home/bam/claude/mvp-factory/.github/workflows/openhands-build.yml`
- ✅ `/home/bam/claude/mvp-factory/.github/scripts/agent_build.py`
- ✅ `/home/bam/claude/mvp-factory/NEW_APPROACH_ANALYSIS.md`
- ✅ `/home/bam/claude/mvp-factory/GITHUB_ACTIONS_INTEGRATION_GUIDE.md`
- ✅ `/home/bam/claude/mvp-factory/MIGRATION_SUMMARY.md` (this file)

### Files to Modify
- 📝 `phase3.md` - Update with new approach
- 📝 `N8N_DATA_PRESERVATION_SOLUTION.md` - Update for GitHub Actions
- 📝 `openhands-subagents-doc.md` - Add SDK examples

### Files to Deprecate
- 📦 `/home/bam/claude/mvp-factory/test-scripts/openhands-sdk-wrapper-sh.sh` (SSH approach)

---

## 🔑 Required Credentials

### GitHub Repository Secrets
```bash
OPENHANDS_API_KEY: sk-... (from /home/bam/openhands/.env)
GITEA_API_TOKEN: gitea_token_... (generate in Gitea)
```

### GitHub Repository Variables
```bash
LLM_MODEL: anthropic/claude-sonnet-4-5-20250929
GITEA_API_URL: https://git.oky.sh
```

### n8n Credentials
```bash
GitHub Token: github_pat_... (with repo + workflow scopes)
Gitea API Token: gitea_token_...
```

---

## 🎯 Key Benefits

### Technical Benefits
1. **Simpler Architecture:** 11 nodes → 5 nodes
2. **Better Error Handling:** SDK native + Actions structured
3. **Cleaner Logging:** File-based + artifact upload
4. **Standard Patterns:** GitHub Actions ecosystem
5. **No SSH Complexity:** Remove wrapper script, keys

### Operational Benefits
1. **Easier Debugging:** GitHub Actions UI
2. **Better Visibility:** Commit status on GitHub
3. **Artifact Retention:** Build logs automatically saved
4. **Retry Management:** GitHub Actions native
5. **Cloud-Native:** Modern CI/CD approach

### Developer Experience
1. **Python SDK:** Direct integration, no shell wrapper
2. **Better Prompts:** Rich context and error feedback
3. **Structured Output:** JSON metadata + logs
4. **Standard Tools:** GitHub, not custom SSH scripts
5. **Future-Proof:** Aligns with modern practices

---

## ⚠️ Risks & Mitigation

### Risk 1: Gitea → GitHub Integration
**Issue:** Need to mirror or use GitHub Actions
**Mitigation:**
- Check if Gitea supports Actions (newer versions do)
- Or use GitHub.com and mirror from Gitea
- Or keep Gitea as source of truth, GitHub for Actions only

### Risk 2: API Key Management
**Issue:** Multiple systems (n8n, GitHub, OpenHands)
**Mitigation:**
- Use GitHub repository secrets (secure)
- Use environment variables (automated)
- Document all required keys clearly

### Risk 3: Learning Curve
**Issue:** Team unfamiliar with GitHub Actions
**Mitigation:**
- Start with simple workflows
- Use provided templates
- Leverage documentation
- Gradual migration

### Risk 4: Timeline Overrun
**Issue:** 3-4 days might be optimistic
**Mitigation:**
- Phase approach (can stop between phases)
- Keep SSH approach as fallback
- Parallel testing

---

## ✅ Success Criteria

### Must Have
- [ ] End-to-end build/test completes successfully
- [ ] n8n orchestrates without SSH
- [ ] GitHub Actions runs OpenHands SDK
- [ ] Gitea status updates automatically
- [ ] Retry logic works (max 3 attempts)
- [ ] Better error messages than SSH approach
- [ ] Logs captured and accessible
- [ ] Simpler code (fewer nodes, less complexity)

### Nice to Have
- [ ] Parallel testing (multiple repos)
- [ ] Slack/Discord notifications
- [ ] Email alerts for failures
- [ ] Build time tracking
- [ ] Detailed metrics dashboard

---

## 📚 Quick Reference

### Start Here
1. **Analysis:** Read `NEW_APPROACH_ANALYSIS.md`
2. **Implementation:** Follow `GITHUB_ACTIONS_INTEGRATION_GUIDE.md`
3. **Migration:** Use this document for tracking

### Key Files
- **Workflow:** `.github/workflows/openhands-build.yml`
- **Agent:** `.github/scripts/agent_build.py`
- **Current Plan:** `phase3.md` (to be updated)

### Commands
```bash
# Test GitHub Actions manually
gh workflow run openhands-build.yml -f task="Build project" -f repo_name="test" -f commit_sha="abc123"

# Check workflow status
gh run list

# View logs
gh run view <run-id>
```

### Resources
- [OpenHands SDK](https://docs.openhands.dev/sdk/)
- [GitHub Actions API](https://docs.github.com/en/rest/actions)
- [n8n HTTP Node](https://docs.n8n.io/integrations/builtin/core-nodes/n8n-nodes-base.httprequest/)

---

## 🚀 Decision Point

**PROCEED with hybrid approach (Option A)**

**Next Action:**
- Day 1: Start with GitHub Actions setup
- Begin with GitHub repository creation and workflow testing
- Use Phase 3 timeline (3-4 days) as guide
- Keep SSH approach as fallback during transition

**Timeline:**
- **Start:** 2025-12-02
- **Expected Completion:** 2025-12-05 (3 days)
- **Phase 1:** Day 1 (GitHub Actions setup)
- **Phase 2:** Day 2 (n8n integration)
- **Phase 3:** Day 3 (testing & retry)
- **Phase 4:** Day 4 (documentation)

---

*Migration Summary - 2025-12-02*
*Decision: Proceed with hybrid approach*