# 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 `packages/github-app/` as the working directory.

## Verification

Run the service checks from the repo root:

```bash
uv run pytest packages/github-app -v
uv run ruff check packages/github-app
uv run ruff format packages/github-app
uv run mypy packages/github-app/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/auth.py` handles GitHub App JWT and installation token authentication.
- `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.
- `github_app/retry.py` provides retry logic with exponential backoff.
- `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`.
