# 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*