# Build Orchestration

**Last Updated:** 2026-01-27
**Confidence:** High

## Summary

Build orchestration enables structured build specs for bot-driven development. Bots submit build requests with prompts and templates via `POST /project/{name}/build`, workers execute Claude Code, and callbacks notify completion. All builds are recorded in the `build_audit` table for observability.

**Key Facts:**
- BuildSpec: prompt (required), template, variables, auto_commit, auto_push, callback_url
- BuildResult: success, output, error, commit_sha, files_changed, duration_ms, artifacts
- Builds enqueued as work tasks for the worker pool
- Auto-commit/push triggers Woodpecker CI pipeline
- Callback URL receives completion notification with full BuildResult
- Complete audit trail in `build_audit` PostgreSQL table

**File Pointers:**
- Domain: `internal/domain/build.go` (BuildSpec, BuildResult, BuildAuditEntry)
- Port: `internal/port/build_audit.go` (BuildAudit interface)
- Adapter: `internal/adapter/postgres/build_audit.go`
- Service: `internal/service/build_service.go`
- Handler: `internal/handlers/builds.go` (StartBuild, ListBuilds, GetBuild)
- Handler: `internal/handlers/create_and_build.go` (CreateAndBuild)
- Executor: `internal/worker/build_executor.go` (BuildSpec→AgentRequest translation)
- Git: `internal/worker/git_operations.go` (clone, commit, push with token injection)
- Migration: `internal/db/migrations/012_worker_registry.sql` (build_audit table)

## API Endpoints

| Method | Path | Description |
|--------|------|-------------|
| POST | `/projects/{id}/builds` | Start a build, returns task_id |
| GET | `/projects/{id}/builds` | List builds for project |
| GET | `/builds/{taskId}` | Get build status and result |
| POST | `/project/create-and-build` | Create project + start build in one call |

## Orchestration Flow

1. Bot calls `POST /projects/{id}/builds` with BuildSpec (prompt, template, auto_commit, auto_push)
2. BuildService validates spec (prompt required), creates WorkTask with build spec, enqueues
3. Creates BuildAuditEntry with status "pending"
4. Returns task ID immediately
5. WorkExecutor poll loop claims task from queue
6. BuildExecutor translates spec: clones repo, builds AgentRequest, calls CodeAgent.Execute()
7. On success with auto_commit: GitOperations commits and pushes changes
8. WorkExecutor reports completion with BuildResult
9. Audit entry updated, callback URL notified

## Build Audit Statuses

- `pending` - enqueued, waiting for worker
- `running` - worker executing
- `completed` - finished successfully
- `failed` - execution failed
- `cancelled` - cancelled before completion

## Related Topics

- [Work Queue](../services/work-queue.md)
- [Worker Pool](../services/worker-pool.md)
- [Template Provider](../services/template-provider.md)