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:

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

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:

#!/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:

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

# 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):

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