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

7.7 KiB
Raw Blame History

Quick Start Checklist - GitHub Actions Integration

Date: 2025-12-02 Approach: Hybrid (n8n + GitHub Actions + OpenHands SDK) Goal: Get started immediately

✅ Pre-Flight Checklist (15 min)

1. Review Decision (5 min)

  • Read EXECUTIVE_SUMMARY.md (overview)
  • Review key benefits: 55% fewer nodes, better logging
  • Confirm 3-4 day timeline is acceptable
  • Decision: PROCEED / HOLD

2. Verify Credentials (5 min)

  • OpenHands API Key: cat /home/bam/openhands/.env | grep API_KEY
  • n8n API Token: cat /home/bam/.n8n_api_key
  • Gitea access: https://git.oky.sh (admin account)
  • GitHub account: https://github.com (for Actions)

3. Check Documentation (5 min)

  • NEW_APPROACH_ANALYSIS.md - Full analysis
  • GITHUB_ACTIONS_INTEGRATION_GUIDE.md - Implementation
  • .github/workflows/openhands-build.yml - Workflow template
  • .github/scripts/agent_build.py - Agent script

🚀 Day 1: GitHub Actions Setup (3 hours)

Hour 1: Repository Setup

Step 1: Create GitHub Repository (20 min)

# Option A: Create new repository on GitHub.com
# Go to https://github.com/new
# Repository name: mvp-factory-openhands-actions
# Public or Private (secrets work in both)

# Option B: Mirror from Gitea (if you have GitHub)
git clone https://git.oky.sh/gitadmin/your-project.git
cd your-project
git remote add github https://github.com/username/your-project.git
git push github main

Step 2: Add Workflow Files (10 min)

# Create directories
mkdir -p .github/workflows .github/scripts

# Copy files from analysis
# (Files already created at:)
# /home/bam/claude/mvp-factory/.github/workflows/openhands-build.yml
# /home/bam/claude/mvp-factory/.github/scripts/agent_build.py

# Make agent script executable
chmod +x .github/scripts/agent_build.py

# Commit and push
git add .github/
git commit -m "Add GitHub Actions workflow for OpenHands"
git push origin main

Step 3: Configure Repository Settings (10 min)

  1. Go to GitHub → Repository → Settings
  2. Secrets and variables → Actions
  3. Click "New repository secret"
  4. Add each secret:
    • Name: OPENHANDS_API_KEY
    • Value: [MiniMax API key from /home/bam/openhands/.env]
  5. Add second secret:
    • Name: GITEA_API_TOKEN
    • Value: [Generate in Gitea → Settings → Applications]

Step 4: Add Variables (10 min)

  1. In same "Secrets and variables" section
  2. Click "Variables" tab
  3. Add each variable:
    • Name: LLM_MODEL
    • Value: anthropic/claude-sonnet-4-5-20250929
    • Name: GITEA_API_URL
    • Value: https://git.oky.sh

Step 5: Verify in Repository (10 min)

# Check files exist
ls -la .github/workflows/
ls -la .github/scripts/

# Verify workflow syntax
cat .github/workflows/openhands-build.yml | head -20
cat .github/scripts/agent_build.py | head -20

Hour 2-3: Test GitHub Actions

Step 6: Test Manually (45 min)

  1. Go to GitHub → Repository → Actions tab
  2. Select "OpenHands Build & Test" workflow
  3. Click "Run workflow" (dropdown)
  4. Fill parameters:
    • Task: Build and test this project
    • Repo Name: your-repo-name
    • Commit SHA: git rev-parse HEAD
    • Retry Count: 0
  5. Click "Run workflow"

Step 7: Monitor Execution (45 min)

  1. Click on running workflow
  2. Watch each step execute:
    • ✅ Checkout repository
    • ✅ Setup Python
    • ✅ Install uv
    • ✅ Install OpenHands SDK
    • ✅ Run Build Task (most important)
    • ✅ Upload Build Logs
    • ✅ Update Gitea Status
  3. Check logs for each step
  4. Verify final status: success ✅ or failure ❌

Step 8: Check Artifacts (15 min)

  1. After workflow completes
  2. Scroll down to "Artifacts" section
  3. Download "build-logs-X" artifact
  4. Verify logs contain:
    • OpenHands initialization
    • Task execution details
    • Build results

Step 9: Verify Gitea Status (15 min)

  1. Go to Gitea → Repository → Commits
  2. Find the commit you built
  3. Check status badge: "success" or "failure"
  4. Click status to see details

Hour 3: Troubleshooting

If Actions fails:

  • Check logs for each step
  • Common issues:
    • Missing OPENHANDS_API_KEY secret
    • Invalid API key format
    • Python setup errors
    • OpenHands SDK installation issues

If Gitea status doesn't update:

  • Check GITEA_API_TOKEN secret is correct
  • Verify token has API access permissions
  • Check GitHub Actions logs for API call errors

Verification Complete When:

  • ✅ GitHub Actions runs successfully
  • ✅ Logs uploaded as artifacts
  • ✅ Gitea commit status updated
  • ✅ Build task completes without errors

📋 Day 1 Success Criteria

All must be checked:

  • GitHub Actions workflow exists
  • Repository secrets configured (OPENHANDS_API_KEY, GITEA_API_TOKEN)
  • Repository variables configured (LLM_MODEL, GITEA_API_URL)
  • Manual test runs successfully
  • Logs uploaded as artifacts
  • Gitea status updated
  • No errors in workflow execution

If all checked: Proceed to Day 2 If any failed: Troubleshoot before moving forward

📚 Day 2 Preview: n8n Integration

Tomorrow's Tasks:

  1. Update existing n8n workflow (ID: j1MmXaRhDjvkRSLa)
  2. Replace SSH node with HTTP node
  3. Add GitHub Actions trigger
  4. Test end-to-end flow
  5. Verify data preservation

Estimated Time: 3-4 hours

🆘 Troubleshooting Guide

Issue: "LLM_API_KEY environment variable is not set"

Solution:

# Check secret exists
# GitHub → Settings → Secrets and variables → Actions → Secrets

# Verify value is correct
echo $OPENHANDS_API_KEY

# If missing, add it:
# GitHub → Settings → Secrets → New secret
# Name: OPENHANDS_API_KEY
# Value: sk-... (from /home/bam/openhands/.env)

Issue: "HTTP 404" when triggering workflow

Solution:

  1. Verify workflow file exists: .github/workflows/openhands-build.yml
  2. Check workflow has workflow_dispatch trigger (line 2-5)
  3. Verify repository name and owner in URL
  4. Ensure token has workflow scope

Issue: "HTTP 403" when triggering workflow

Solution:

  1. Check GitHub token permissions
  2. Token needs: repo, workflow scopes
  3. Verify token is not expired
  4. Try regenerating token

Issue: "Build failed" but no clear error

Solution:

  1. Download build logs artifact
  2. Check build.log file
  3. Look for OpenHands SDK errors
  4. Check if task is too complex (simplify)

Issue: "Gitea status not updating"

Solution:

# Test token manually
curl -H "Authorization: token YOUR_TOKEN" \
  https://git.oky.sh/api/v1/user

# If 401: Token is invalid
# If 200: Token works, check repository name/sha

📞 Support Resources

Documentation

Local Files

  • /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

Current System

✅ Decision Point

After completing Day 1:

If successful:

  • ✅ All tests pass
  • ✅ GitHub Actions working
  • ✅ Gitea status updating
  • Action: Proceed to Day 2 (n8n integration)

If issues persist:

  • ❌ Multiple failures
  • ❌ Can't resolve errors
  • Action: Pause and reassess
    • Review NEW_APPROACH_ANALYSIS.md
    • Consider staying with SSH approach
    • Or debug issues before proceeding

Overall Decision: Day 1 success = GO for Day 2 Day 1 failure = EVALUATE & DECIDE

Quick Start Checklist - 2025-12-02 Ready to begin implementation