hive/docs/GITEA_INTEGRATION.md

WHOOSH GITEA Integration Guide

Overview

WHOOSH integrates with the GITEA instance running on IRONWOOD (http://ironwood:3000) to provide comprehensive project repository management and BZZZ task coordination.

🔧 Corrected Infrastructure Details

• GITEA Server: http://ironwood:3000 (IRONWOOD node)
• External Access: gitea.deepblack.cloud (via Traefik reverse proxy)
• API Endpoint: http://ironwood:3000/api/v1
• Integration: Complete BZZZ task coordination via GITEA API
• Authentication: Personal access tokens

🚀 Setup Instructions

1. GITEA Token Configuration

To enable full WHOOSH-GITEA integration, you need a personal access token:

Create Token in GITEA:

1. Visit http://ironwood:3000/user/settings/applications
2. Click "Generate New Token"
3. Set token name: WHOOSH Integration
4. Select permissions:
   • ✅ read:user (required for API user operations)
   • ✅ write:repository (create and manage repositories)
   • ✅ write:issue (create and manage issues)
   • ✅ read:organization (if using organization repositories)
   • ✅ write:organization (if creating repositories in organizations)

Store Token Securely:

Choose one of these methods (in order of preference):

Option 1: Docker Secret (Most Secure)

echo "your_gitea_token_here" | docker secret create gitea_token -

Option 2: Filesystem Secret

mkdir -p /home/tony/AI/secrets/passwords_and_tokens/
echo "your_gitea_token_here" > /home/tony/AI/secrets/passwords_and_tokens/gitea-token
chmod 600 /home/tony/AI/secrets/passwords_and_tokens/gitea-token

Option 3: Environment Variable

export GITEA_TOKEN="your_gitea_token_here"

2. Verify Integration

Run the integration test to verify everything is working:

cd /home/tony/chorus/project-queues/active/WHOOSH
python3 test_gitea_integration.py

Expected output with token configured:

✅ GITEA Service initialized
✅ Found X repositories  
✅ Repository validation successful
✅ BZZZ integration features verified
🎉 All tests passed! GITEA integration is ready.

🏗️ Integration Architecture

WHOOSH → GITEA Flow

WHOOSH Project Setup Wizard
    ↓
GiteaService.create_repository()
    ↓
GITEA API: Create Repository
    ↓
GiteaService._setup_bzzz_labels()
    ↓
GITEA API: Create Labels
    ↓
Project Ready for BZZZ Coordination

BZZZ → GITEA Task Coordination

BZZZ Agent Discovery
    ↓
GiteaService.get_bzzz_tasks()
    ↓
GITEA API: List Issues with 'bzzz-task' label
    ↓
BZZZ Agent Claims Task
    ↓
GITEA API: Assign Issue + Add Comment
    ↓
BZZZ Agent Completes Task
    ↓
GITEA API: Close Issue + Results Comment

🏷️ BZZZ Label System

The following labels are automatically created for BZZZ task coordination:

Core BZZZ Labels

• bzzz-task - Task available for BZZZ agent coordination
• in-progress - Task currently being worked on
• completed - Task completed by BZZZ agent

Task Type Labels

• frontend - Frontend development task
• backend - Backend development task
• security - Security-related task
• design - UI/UX design task
• devops - DevOps and infrastructure task
• documentation - Documentation task
• bug - Bug fix task
• enhancement - Feature enhancement task
• architecture - System architecture task

Priority Labels

• priority-high - High priority task
• priority-low - Low priority task

📋 Project Creation Workflow

1. Through WHOOSH UI

The enhanced project setup wizard now includes:

// Project creation with GITEA integration
const projectData = {
  name: "my-new-project",
  description: "Project description",
  git_config: {
    repo_type: "new",           // new|existing|import
    repo_name: "my-new-project",
    git_owner: "whoosh",        // GITEA user/organization
    private: false,
    auto_initialize: true
  },
  bzzz_config: {
    enable_bzzz: true,          // Enable BZZZ task coordination
    task_coordination: true,
    ai_agent_access: true
  }
}

2. Automated Repository Setup

When creating a new project, WHOOSH automatically:

1. Creates GITEA Repository

   • Sets up repository with README, .gitignore, LICENSE
   • Configures default branch and visibility

2. Installs BZZZ Labels

   • Adds all task coordination labels
   • Sets up proper color coding and descriptions

3. Creates Initial Task

   • Adds "Project Setup" issue with bzzz-task label
   • Provides template for future task creation

4. Configures Integration

   • Links project to repository in WHOOSH database
   • Enables BZZZ agent discovery

🤖 BZZZ Agent Integration

Task Discovery

BZZZ agents discover tasks by:

// In BZZZ agent
config := &gitea.Config{
    BaseURL:     "http://ironwood:3000",
    AccessToken: os.Getenv("GITEA_TOKEN"),
    Owner:       "whoosh",
    Repository:  "project-name",
}

client, err := gitea.NewClient(ctx, config)
tasks, err := client.ListAvailableTasks()

Task Claiming

// Agent claims task
task, err := client.ClaimTask(issueNumber, agentID)
// Automatically:
// - Assigns issue to agent
// - Adds 'in-progress' label  
// - Posts claim comment

Task Completion

// Agent completes task
results := map[string]interface{}{
    "files_modified": []string{"src/main.go", "README.md"},
    "tests_passed": true,
    "deployment_ready": true,
}

err := client.CompleteTask(issueNumber, agentID, results)
// Automatically:
// - Closes issue
// - Adds 'completed' label
// - Posts results comment

🔍 Monitoring and Management

WHOOSH Dashboard Integration

The WHOOSH dashboard shows:

• Repository Status: Connected GITEA repositories
• BZZZ Task Count: Open tasks available for agents
• Agent Activity: Which agents are working on which tasks
• Completion Metrics: Task completion rates and times

GITEA Repository View

In GITEA, you can monitor:

• Issues: All BZZZ tasks show as labeled issues
• Activity: Agent comments and task progression
• Labels: Visual task categorization and status
• Milestones: Project progress tracking

🔧 Troubleshooting

Common Issues

"No GITEA token found"

• Solution: Configure token using one of the methods above

"Repository creation failed"

• Check token has repository permissions
• Verify GITEA server is accessible at http://ironwood:3000
• Ensure target organization/user exists

"BZZZ tasks not discovered"

• Verify issues have bzzz-task label
• Check BZZZ agent configuration points to correct repository
• Confirm token has issue permissions

"API connection timeout"

• Verify IRONWOOD node is accessible on network
• Check GITEA service is running: docker service ls | grep gitea
• Test connectivity: curl http://ironwood:3000/api/v1/version

Debug Commands

# Test GITEA connectivity
curl -H "Authorization: token YOUR_TOKEN" \
     http://ironwood:3000/api/v1/user

# List repositories
curl -H "Authorization: token YOUR_TOKEN" \
     http://ironwood:3000/api/v1/user/repos

# Check BZZZ tasks in repository
curl -H "Authorization: token YOUR_TOKEN" \
     "http://ironwood:3000/api/v1/repos/OWNER/REPO/issues?labels=bzzz-task"

📈 Performance Considerations

API Rate Limits

• GITEA default: 5000 requests/hour per token
• WHOOSH caches repository information locally
• BZZZ agents use efficient polling intervals

Scalability

• Single GITEA instance supports 100+ repositories
• BZZZ task coordination scales to 50+ concurrent agents
• Repository operations are asynchronous where possible

🔮 Future Enhancements

Planned Features

• Webhook Integration: Real-time task updates
• Advanced Task Routing: Agent capability matching
• Cross-Repository Projects: Multi-repo BZZZ coordination
• Enhanced Metrics: Detailed agent performance analytics
• Automated Testing: Integration with CI/CD pipelines

Integration Roadmap

1. Phase 1: Basic repository and task management ✅
2. Phase 2: Advanced agent coordination (in progress)
3. Phase 3: Cross-project intelligence sharing
4. Phase 4: Predictive task allocation

---

📞 Support

For issues with GITEA integration:

1. Check Integration Test: Run python3 test_gitea_integration.py
2. Verify Configuration: Ensure token and connectivity
3. Review Logs: Check WHOOSH backend logs for API errors
4. Test Manually: Use curl commands to verify GITEA API access

GITEA Integration Status: ✅ Production Ready
BZZZ Coordination: ✅ Active
Agent Discovery: ✅ Functional