codeflash-agent/services/github-app/CLAUDE.md

GitHub App Service Guide

Thin webhook dispatcher for CI mode. Receives GitHub webhooks, clones the repo, writes .codeflash/ci-context.json, and invokes the codeflash-ci plugin agent.

Working Directory

When you run service-specific commands, use services/github-app/ as the working directory.

Verification

Run the service checks from services/github-app/:

uv run pytest -v
uv run ruff check github_app tests
uv run ruff format github_app tests
uv run mypy github_app

Structure

• github_app/app.py owns FastAPI lifecycle, webhook routing, CI context writing, and agent invocation.
• github_app/agents.py runs the CLI backend (Claude/Codex) with GITHUB_TOKEN for gh CLI auth.
• github_app/github.py contains GitHub API helpers (used by other services, not by dispatch handlers).
• github_app/backends.py defines CLI backend specs (Claude, Codex) and command building.
• github_app/config.py loads environment-based configuration.
• github_app/git.py handles repo cloning and workspace management.
• tests/ uses async pytest patterns and validates webhook behavior and agent invocation.

Conventions

• Dispatch handlers are thin: extract metadata, write JSON context, call run_agent().
• The agent handles all GitHub interactions via gh CLI (not the service).
• Keep handlers non-blocking and register them through EVENT_HANDLERS.