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:

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

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:

./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:

# Add to your configuration
logging:
  level: debug

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