gitadmin
/
mvp-factory-openhands
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
mvp-factory-openhands/MIGRATION_SUMMARY.md

8.5 KiB
Raw Permalink Blame History

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

OPENHANDS_API_KEY: sk-... (from /home/bam/openhands/.env)
GITEA_API_TOKEN: gitea_token_... (generate in Gitea)

GitHub Repository Variables

LLM_MODEL: anthropic/claude-sonnet-4-5-20250929
GITEA_API_URL: https://git.oky.sh

n8n Credentials

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

# 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

🚀 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