Skip to main content

Overview

Builds represent individual deployment attempts for your project. Each build tracks the commit SHA, build status, timing information, and logs.

Build Model

Each build in the system contains:

Build Status States

pending

Build is queued or in progress

success

Build completed successfully

failed

Build process failed

Get Project Builds

GET /api/projects/:id/builds

Retrieve build history for a project (up to 50 most recent builds).
Authentication Required: Yes (JWT) Path Parameters:
string
required
Project ID (MongoDB ObjectId)
Response:
Query Details:
Builds are sorted by creation date in descending order (newest first) and limited to 50 results.

Get Single Build

GET /api/projects/:id/builds/:buildId

Retrieve detailed information for a specific build.
Authentication Required: Yes (JWT) Path Parameters:
string
required
Project ID (MongoDB ObjectId)
string
required
Build ID (MongoDB ObjectId)
Response:
The single build endpoint includes the dockerImage field, which is not included in the list view.

Build Indexing

Builds are indexed for efficient querying:
This compound index optimizes queries that:
  • Filter by project ID
  • Sort by creation date in descending order

Build Creation Process

When a new deployment is created, the build process:

1. Fetch Commit SHA

2. Create Build Record

3. Update Project Reference

4. Queue Build Job

Build Duration Calculation

Build duration is calculated from the difference between startedAt and finishedAt:
Format:
  • Less than 60 seconds: "34s"
  • 60 seconds or more: "2m 34s"

Total Build Counter

The project maintains a totalBuilds counter:
This counter is incremented each time a new build is created, providing a quick reference without counting all build documents.

Example: Monitor Build Progress

Example: Display Build History

Build Queue System

Builds are processed asynchronously through a queue system: Queue Name: buildqueue Job Data:
Worker: /src/workers/buildworker.js The build worker:
  1. Fetches build and project details
  2. Clones the repository
  3. Builds Docker image
  4. Updates build status and timing
  5. Triggers deployment if successful

Error Responses

404 Not Found - Project

404 Not Found - Build

500 Server Error

Build Logs

The logUrl field points to the location of build logs:
Logs are typically stored externally and linked to each build for debugging failed builds or reviewing build output.
Build logs are generated during the build worker process and stored separately from the build metadata.