Files

CI System c6d18d0b5e docs: fix workflow diagram - merge happens after Verify

The merge to main occurs after the QA verification step succeeds,
not after Review/Done.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

2025-12-10 21:07:58 -07:00

2.8 KiB

Raw Permalink Blame History

ClearGrow Agent Runner

Automated task orchestration system that monitors YouTrack issues and coordinates Claude Code agents to resolve them across Gitea repositories, with Woodpecker CI verification.

Overview

The Agent Runner automates the software development workflow:

Ready → In Progress → Build → Verify → Document → Review → Done
         (Developer)   (CI)    (QA)      (Librarian)
              ↑          │        ↓
              └──────────┘    Merge to main
            (on build failure)

Components

File	Purpose
`runner.py`	Main orchestration engine
`agent.py`	Claude Code subprocess pool management
`youtrack_client.py`	YouTrack API wrapper
`gitea_client.py`	Gitea API wrapper + git CLI operations
`woodpecker_client.py`	Woodpecker CI build monitoring
`webhook_server.py`	HTTP webhook receiver for real-time events
`prompts/`	Prompt templates for Claude agents

Agent Types

Agent	Token	Purpose
Developer	`agent_tokens.developer`	Code remediation and bug fixes
QA	`agent_tokens.qa`	Code verification and review
Librarian	`agent_tokens.librarian`	Documentation updates
Build	`agent_tokens.build`	CI build status comments

Configuration

Copy the example config and fill in your credentials:

cp config.yaml.example config.yaml
chmod 600 config.yaml

Required configuration:

youtrack.base_url and youtrack.token
gitea.base_url and gitea.token
woodpecker.base_url and woodpecker.token
agent_tokens.* for each agent type
repos.* mapping repositories to local paths

Installation

# Create virtual environment
python3 -m venv venv
source venv/bin/activate

# Install dependencies
pip install -r requirements.txt

# Configure
cp config.yaml.example config.yaml
vim config.yaml

# Run
python runner.py -c config.yaml

Systemd Service

sudo cp cleargrow-agent-runner.service /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable cleargrow-agent-runner
sudo systemctl start cleargrow-agent-runner

Workflow

Ready: Issue waiting for remediation
In Progress: Developer agent working on fix
Build: Woodpecker CI building feature branch
Verify: QA agent reviewing changes → merges to main on success
Document: Librarian agent updating docs
Review: Human review (manual)
Done: Complete

Branch Convention

Feature branches follow the pattern: issue/{ISSUE_ID}

Example: Issue CG-47 → branch issue/CG-47

API Integrations

YouTrack: Issue tracking and state management
Gitea: Repository hosting and git operations
Woodpecker CI: Automated builds on push

License

Proprietary - ClearGrow

2.8 KiB Raw Permalink Blame History