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)**
```bash
echo "your_gitea_token_here" | docker secret create gitea_token -
```

**Option 2: Filesystem Secret**
```bash
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**
```bash
export GITEA_TOKEN="your_gitea_token_here"
```

### 2. Verify Integration

Run the integration test to verify everything is working:

```bash
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:

```typescript
// 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:

```go
// 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

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

### Task Completion

```go
// 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

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