How aparnamol-ks/shipforge works
ShipForge is a self-hosted CI/CD service. Users configure projects and pipeline commands in the React dashboard, then manually trigger builds or receive GitHub push-triggered builds. The API records build state and enqueues jobs; a Redis worker runs configured stages in Docker, records results and logs, and publishes events for dashboard updates. The graph includes documented capabilities such as retries, cancellation, and polling; several subsystem links rely on the README because their implementation was not excerpted.
Main entry points: runner.py Build runner · router.py Build endpoints · github.py GitHub webhook · pages Project pages
Components 27
Dashboard
- React dashboard
frontend/src/App.tsx - Project pages
frontend/src/pages - Project controls
frontend/src/components - Build history
frontend/src/components/BuildList.tsx - API client
frontend/src/api/projects.ts - Build updates hook
frontend/src/hooks/useBuildWebSocket.ts
API and projects
- FastAPI app
backend/app/main.py - Project endpoints
backend/app/projects/router.py - Project management
backend/app/projects/service.py - GitHub webhook
backend/app/webhooks/github.py - Build endpoints
backend/app/builds/router.py - Build lifecycle
backend/app/builds/service.py
Build execution
- Queue worker
backend/app/redis_client/worker.py - Build runner
backend/app/builds/runner.py - Workspace handling
backend/app/builds/workspace_service.py - Repository handling
backend/app/repositories/service.py - Docker executor
backend/app/builds/docker_executor.py
Persistence and events
- PostgreSQL data
backend/app/database/models.py - Database sessions
backend/app/database/connection.py - Redis queue
backend/app/redis_client/queue.py - Redis events
backend/app/redis_client/events.py - Event subscriber
backend/app/redis_client/subscriber.py - Build event listener
backend/app/builds/event_listener.py - WebSocket endpoint
backend/app/builds/websocket.py - Build logs
backend/app/builds/log_service.py
Other components
- User
- GitHub
Connections 41
- User → React dashboard: uses
- React dashboard → Project pages: routes to
frontend/src/App.tsx - Project pages → Project controls: renders
frontend/src/pages/ProjectsPage.tsx - Project pages → Build history: renders
frontend/src/pages/ProjectDetailsPage.tsx - Project controls → API client: calls
frontend/src/components/ProjectForm.tsx - Build history → API client: calls
frontend/src/components/BuildList.tsx - Project pages → API client: loads data
frontend/src/pages/ProjectDetailsPage.tsx - Project pages → Build updates hook: opens updates
frontend/src/pages/ProjectDetailsPage.tsx - Build updates hook → WebSocket endpoint: connects
frontend/src/hooks/useBuildWebSocket.ts - API client → FastAPI app: HTTP requests
frontend/src/api/projects.ts - FastAPI app → Project endpoints: registers
backend/app/main.py - FastAPI app → Build endpoints: registers
backend/app/main.py - FastAPI app → GitHub webhook: registers
backend/app/main.py - Project endpoints → Project management: calls
backend/app/projects/router.py - Project management → PostgreSQL data: reads and writes
backend/app/projects/service.py - GitHub webhook → GitHub: receives push
- GitHub → GitHub webhook: sends push
- GitHub webhook → Project management: matches repository
backend/app/webhooks/github.py - GitHub webhook → Build lifecycle: creates build
backend/app/webhooks/github.py - GitHub webhook → Redis queue: schedules build
backend/app/webhooks/github.py - Build endpoints → Project management: checks project
backend/app/builds/router.py - Build endpoints → Build lifecycle: manages lifecycle
backend/app/builds/router.py - Build endpoints → Redis queue: schedules build
backend/app/builds/router.py - Build lifecycle → PostgreSQL data: reads and writes
backend/app/builds/service.py - Queue worker → Redis queue: dequeues
backend/app/redis_client/worker.py - Queue worker → PostgreSQL data: loads records
backend/app/redis_client/worker.py - Queue worker → Build runner: runs build
backend/app/redis_client/worker.py - Build runner → Repository handling: handles checkout
backend/app/builds/runner.py - Build runner → Workspace handling: manages workspace
backend/app/builds/runner.py - Build runner → Docker executor: executes stages
backend/app/builds/runner.py - Build runner → Build lifecycle: updates state
backend/app/builds/runner.py - Build runner → Build logs: records output
backend/app/builds/runner.py - Build runner → Redis events: publishes events
backend/app/redis_client/worker.py - Build logs → PostgreSQL data: stores logs
backend/app/builds/log_service.py - Redis events → Event subscriber: publishes stream
backend/app/redis_client/subscriber.py - Build event listener → Event subscriber: subscribes
backend/app/builds/event_listener.py - Build endpoints → Build event listener: forwards events
backend/app/builds/router.py - Build event listener → WebSocket endpoint: forwards updates
backend/app/builds/router.py - WebSocket endpoint → Build updates hook: sends events
- Build endpoints → Build logs: reads logs
backend/app/builds/router.py - API client → Build endpoints: requests builds
frontend/src/api/projects.ts