288 lines
7.7 KiB
Markdown
288 lines
7.7 KiB
Markdown
# 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)**
|
|
```bash
|
|
# 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)**
|
|
```bash
|
|
# 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)**
|
|
```bash
|
|
# 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:**
|
|
```bash
|
|
# 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:**
|
|
```bash
|
|
# 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
|
|
- **OpenHands SDK:** https://docs.openhands.dev/sdk/
|
|
- **GitHub Actions API:** https://docs.github.com/en/rest/actions
|
|
- **Gitea API:** https://docs.gitea.io/en-us/api-usage/
|
|
|
|
### 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
|
|
- **n8n:** https://n8n.oky.sh
|
|
- **Gitea:** https://git.oky.sh
|
|
- **Working workflow:** ID: j1MmXaRhDjvkRSLa
|
|
|
|
---
|
|
|
|
## ✅ 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*
|