GERRIT.md

# Gerrit Integration Guide

Staff AI Agent System now supports Gerrit as an alternative to GitHub for pull request management. This guide explains how to configure and use Gerrit with Staff.

## Overview

Gerrit integration provides the same capabilities as GitHub:
- Create changes (Gerrit's equivalent of pull requests)
- List and manage changes
- Update change descriptions
- Close (abandon) changes
- Submit (merge) changes
- Structured logging for all operations

## Configuration

### YAML Configuration

Add Gerrit configuration to your `config.yaml`:

```yaml
# Either GitHub OR Gerrit is required
gerrit:
  username: "your-gerrit-username" 
  password: "your-gerrit-http-password-or-token"
  base_url: "https://gerrit.example.com"
  project: "your-project-name"
```

### Environment Variables

You can also configure Gerrit using environment variables:

```bash
export GERRIT_USERNAME="your-username"
export GERRIT_PASSWORD="your-password-or-token"
export GERRIT_BASE_URL="https://gerrit.example.com" 
export GERRIT_PROJECT="your-project"
```

## Provider Priority

When both GitHub and Gerrit are configured, GitHub takes precedence for backward compatibility. To use Gerrit when both are configured, remove the GitHub configuration.

## Authentication

Gerrit integration supports:
- **HTTP Password**: Traditional Gerrit HTTP password
- **HTTP Token**: Generate from Gerrit Settings → HTTP Credentials

## URL Format

Generated change URLs follow Gerrit's standard format:
```
https://gerrit.example.com/c/project-name/+/12345
```

## Agent Behavior

Agents work identically with Gerrit:
1. Process assigned tasks
2. Generate solutions using LLM
3. Create Git branches and commits
4. Create Gerrit changes for review
5. Update task status with change URL

## Configuration Validation

Use the config check command to verify your Gerrit setup:

```bash
./staff config-check
```

This will show:
- Which Git provider is configured (GitHub/Gerrit)
- Validation of all required fields
- Connection status

## Example Configuration

See `config-gerrit-example.yaml` for a complete example configuration using Gerrit instead of GitHub.

## Structured Logging

All Gerrit operations include structured logging:

```
INFO Creating Gerrit change url=https://gerrit.example.com/a/changes/ project=my-project subject="Task ABC-123: Implement feature" branch=main topic=task/ABC-123-implement-feature
```

## Comparison with GitHub

| Feature | GitHub | Gerrit |
|---------|--------|--------|
| Changes/PRs | Pull Requests | Changes |
| Review System | GitHub Reviews | Gerrit Code Review |
| Merge | Merge PR | Submit Change |
| Close | Close PR | Abandon Change |
| URL Format | `/pull/123` | `/c/project/+/123` |
| Authentication | Token | Username + Password/Token |

## Migration

To migrate from GitHub to Gerrit:

1. Update configuration file or environment variables
2. Remove GitHub configuration 
3. Restart the Staff system
4. All new agent operations will use Gerrit

Existing GitHub pull requests are not affected and remain accessible.

## Troubleshooting

### Common Issues

1. **Authentication Failed**
   - Verify username and password/token
   - Check Gerrit HTTP credentials settings
   - Ensure HTTP authentication is enabled

2. **Project Not Found**
   - Verify project name matches exactly
   - Check user has access to the project
   - Ensure project exists in Gerrit

3. **Network Issues**
   - Verify base URL is correct and accessible
   - Check firewall/proxy settings
   - Test connectivity to Gerrit server

### Debug Logging

Enable debug logging to troubleshoot issues:

```yaml
# Add to your configuration
logging:
  level: debug
```

This will show detailed HTTP requests and responses for Gerrit operations.