298 lines
8.5 KiB
Markdown
298 lines
8.5 KiB
Markdown
# 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*
|