CTO/docs/INTEGRATION-AUTOMATION.md

# Integration Automation Guide

**Purpose:** Configure automatic merging of feature branches to INTEGRATION-WIP for continuous testing  
**Platform:** Git-native (recommended) or Gitea Actions

## Git-Native Auto-Merge (RECOMMENDED)

**Simplest and most reliable approach using git hooks:**

```bash
# Setup automatic git-native integration
./setup-git-auto-merge.sh
```

**How it works:**
- Uses git `post-commit` hooks to automatically merge feature branches to INTEGRATION-WIP
- No external workflows, runners, or Gitea Actions required
- Conflicts handled gracefully with clear error messages
- INTEGRATION-WIP automatically pushed when feature branches are pushed
- Pure git solution - works with any git hosting platform

**Advantages:**
- ✅ No dependency on Gitea Actions or runners
- ✅ Works immediately after setup
- ✅ Handles conflicts gracefully  
- ✅ Faster than workflow-based solutions
- ✅ No external service dependencies

## Alternative: Gitea Actions Integration

**Only use if git-native approach doesn't meet specific requirements:**

**Automatic setup:** Use `./setup-integration-automation.sh` (recommended)

**Manual setup:** Create `.gitea/workflows/auto-integrate.yml`:

```yaml
name: CTO Delegation - Auto-Merge to Integration

on:
  push:
    branches:
      - 'feature/**'
      - 'bootstrap'

jobs:
  auto-integrate:
    runs-on: ubuntu-latest
    
    steps:
    - name: Checkout code
      uses: actions/checkout@v4
      with:
        fetch-depth: 0
        
    - name: Configure Git
      run: |
        git config user.name "CTO Integration Bot"
        git config user.email "integration@$(git remote get-url origin | sed 's/.*@//; s/:.*//; s/\.git$//')"
        
    - name: Auto-merge to INTEGRATION-WIP
      run: |
        echo "🔄 Starting auto-merge process for ${{ github.ref_name }}"
        
        git checkout INTEGRATION-WIP
        git pull origin INTEGRATION-WIP
        
        BRANCH_NAME="${{ github.ref_name }}"
        echo "📋 Merging $BRANCH_NAME to INTEGRATION-WIP for integration testing"
        
        if git merge origin/$BRANCH_NAME --no-ff -m "🔄 Auto-Integration: $BRANCH_NAME → INTEGRATION-WIP

        Branch: $BRANCH_NAME  
        Commit: ${{ github.sha }}
        Author: ${{ github.actor }}
        Timestamp: $(date -u '+%Y-%m-%d %H:%M:%S UTC')
        
        🤖 CTO AI Delegation Framework - Integration Automation"; then
          
          git push origin INTEGRATION-WIP
          echo "✅ Successfully merged $BRANCH_NAME to INTEGRATION-WIP"
          
        else
          echo "❌ Merge conflict detected for $BRANCH_NAME"
          git merge --abort
          exit 1
        fi
        
    - name: Integration Success Notification
      if: success()
      run: |
        echo "🎯 Integration completed successfully"
        echo "Branch: ${{ github.ref_name }} → INTEGRATION-WIP"
        
    - name: Integration Failure Handling
      if: failure()
      run: |
        echo "🚨 INTEGRATION FAILURE - Manual CTO Resolution Required"
        echo "Branch: ${{ github.ref_name }}"
        echo "Conflict with: INTEGRATION-WIP"
```

## Gitea-Exclusive Setup

Create `setup-integration-automation.sh`:

```bash
#!/bin/bash

echo "🔧 Setting up Integration Automation"

# Detect platform
if [ -d ".github" ] || [ "$1" == "github" ]; then
    PLATFORM="github"
elif [ -d ".gitea" ] || [ "$1" == "gitea" ]; then
    PLATFORM="gitea"
elif [ -f ".gitlab-ci.yml" ] || [ "$1" == "gitlab" ]; then
    PLATFORM="gitlab"
else
    echo "🤔 Couldn't detect platform. Please specify: github, gitea, or gitlab"
    read -p "Enter platform: " PLATFORM
fi

echo "📋 Setting up for: $PLATFORM"

case $PLATFORM in
    "github")
        mkdir -p .github/workflows
        cp docs/workflows/github-auto-integrate.yml .github/workflows/auto-integrate.yml
        echo "✅ GitHub Actions workflow created"
        echo "📝 Remember to set up repository secrets if needed"
        ;;
    "gitea")
        mkdir -p .gitea/workflows
        cp docs/workflows/gitea-auto-integrate.yml .gitea/workflows/auto-integrate.yml
        echo "✅ Gitea Actions workflow created"
        echo "📝 Remember to set GITEA_TOKEN secret"
        ;;
    "gitlab")
        cp docs/workflows/gitlab-ci.yml .gitlab-ci.yml
        echo "✅ GitLab CI configuration created"
        ;;
esac

echo "🎯 Integration automation setup complete!"
echo "📋 Feature branches will now auto-merge to INTEGRATION-WIP"
```

## AI Agent Instructions Update

Add to AGENT-LLM.MD:

```markdown
## INTEGRATION AUTOMATION
**Automatic process - no action required**
- Feature branches automatically merge to INTEGRATION-WIP
- Conflicts require manual resolution
- Check INTEGRATION-WIP branch for test results
- Failed integrations create issues/notifications
```

## Testing the Integration

```bash
# Test the automation
git checkout bootstrap
git checkout -b feature/test-integration
echo "test" > test-file.txt
git add test-file.txt
git commit -m "Test integration automation"
git push origin feature/test-integration

# Check INTEGRATION-WIP after CI runs
git checkout INTEGRATION-WIP
git pull origin INTEGRATION-WIP
git log --oneline -5  # Should see auto-merge commit
```

## Troubleshooting

**Common Issues:**
1. **Permission denied** - Ensure bot token has write access
2. **Merge conflicts** - Manual resolution required
3. **Branch protection** - Adjust rules for INTEGRATION-WIP
4. **CI failures** - Check workflow logs for details

**Manual Integration (Fallback):**
```bash
git checkout INTEGRATION-WIP
git pull origin INTEGRATION-WIP
git merge origin/feature/branch-name --no-ff -m "Manual integration: feature/branch-name"
git push origin INTEGRATION-WIP
```