# 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/pod_git_operations.go` (post-build commit/push via kubectl exec)
- 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 builds AgentRequest, calls CodeAgent.Execute() in pod via kubectl exec
7. **Post-build phase**: If auto_commit, PodGitOperations runs `git add/commit/push` in pod
   - Git operations are programmatic, not LLM-driven (deterministic)
8. WorkExecutor reports completion with BuildResult (includes commit_sha, files_changed)
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)