Git repository builds

Use these routes to trigger Git repository builds manually, inspect history, and read incremental logs. The older route names remain available for existing GitHub projects.

Required permissions

Use project.deploy.trigger on project:<project-id> to trigger a deploy and project.logs.read to read builds and logs. Source and command configuration requires project.source.update. owner has full access; assistant, member, and organization API Keys need the corresponding grant.

Update GitHub commands and root directory

PATCH /v1/project/:id/github/commands

Updates the commands and root directory of a GitHub project and starts a new build. Requires project.source.update. Send at least one of the fields below; omitted fields keep their current value.

{
  "start_command": "npm start",
  "build_command": "npm run build",
  "context_path": "apps/api"
}

Response

{
  "status": "success",
  "message": "GitHub commands updated and build triggered successfully",
  "data": {
    "build_id": "6650f1a2b3c4d5e6f7a8b9c1"
  }
}

The 202 response includes the build_id of the started build; follow it with the build routes below.

Errors

Update GitHub deployment settings

PATCH /v1/project/:id/github/deploy-settings

Send at least one of the fields below. Supplied properties are applied to the current settings, then the resulting mode combination is validated.

The pattern supports only * (any sequence of characters) and ? (one character). For example, v* matches v1.2.0; character classes such as [12], control characters, and other glob syntax are not accepted. In tag mode, only tag creation starts a publication; tag updates and deletions do not.

The modes are exclusive. When switching from the current mode, send the properties needed to leave the final state in exactly one mode. These examples show a complete body for each option:

Example request to publish when a new v* tag is created:

PATCH /v1/project/507f1f77bcf86cd799439011/github/deploy-settings
Content-Type: application/json

{
  "auto_deploy": false,
  "version_deploy": {
    "enabled": true,
    "event": "tag",
    "tag_pattern": "v*",
    "include_prereleases": false
  }
}

Response

For brevity, this example shows the public fields related to the update mode; the response can also include the project's configured runtime and commands.

{
  "status": "success",
  "message": "GitHub deploy settings updated successfully",
  "data": {
    "repository_owner": "example-org",
    "repository_name": "web-app",
    "branch": "main",
    "auto_deploy": false,
    "version_deploy": {
      "enabled": true,
      "event": "tag",
      "tag_pattern": "v*",
      "include_prereleases": false
    }
  }
}

data contains the public GitHub configuration. Older settings may omit version_deploy; without that object, tag and release publications are disabled, and auto_deploy indicates whether the project uses manual or automatic-by-branch mode.

Errors

These logs are different from GET /v1/project/:id/logs, which returns logs from the running application. Build routes return publication history and logs.

Neutral routes for Git builds

Use these routes for projects with a Git source. Response envelopes retain the existing public build and log fields.

Trigger a manual deploy

POST /v1/project/:id/deploy

Rate limit: 10 per minute (counted per source IP).

The body accepts optional branch and commit_sha; commit_sha must be 40 or 64 hexadecimal characters. Without an override, the project uses its configured branch. For GitHub projects in By Tag and By Release modes, send an empty body: the build publishes the latest version matching the pattern. In these modes, branch or commit_sha return 400 (GIT_VERSION_REF_OVERRIDE), and no matching version returns 409 (GIT_VERSION_NOT_FOUND). The response is 202:

{
  "status": "success",
  "message": "Build triggered successfully",
  "data": {
    "build_id": "665f1f77bcf86cd799439011"
  }
}

List builds

GET /v1/project/:id/builds

Rate limit: 60 per minute (counted per source IP).

Optional query parameters are page, limit, branch, and status.

{
  "status": "success",
  "data": [],
  "pagination": {
    "total": 0,
    "page": 1,
    "limit": 10
  }
}

Get a build

GET /v1/project/:id/builds/:buildId

Rate limit: 60 per minute (counted per source IP).

The response uses { "status": "success", "data": Build }. Build fields remain the existing public fields; responses do not include credentials or internal source identifiers.

Read incremental logs

GET /v1/project/:id/builds/:buildId/logs?cursor=0&limit=200

Rate limit: 120 per minute (counted per source IP).

cursor and limit are numeric. The response contains new chunks, the next cursor, and current status:

{
  "status": "success",
  "data": {
    "logs": [],
    "next_cursor": 0,
    "status": "building",
    "finished": false,
    "truncated": false
  }
}

Use next_cursor in the next request to fetch only new lines. finished says the build reached a final state (success, failed, or superseded, when a newer build of the project replaced it and it will not be published); truncated says the public log was limited.

GitHub compatibility routes

The /github/* routes below preserve compatibility with existing GitHub projects. For a generic Git source, use the neutral routes on this page.

Trigger a manual build

POST /v1/project/:id/github/deploy

Rate limit: 10 per minute (counted per source IP).

Body

In By Tag and By Release modes, send an empty body: the build publishes the latest version matching the pattern. branch or commit_sha return 400, and no matching version returns 409.

Response

The response is 202:

{
  "status": "success",
  "message": "Build triggered successfully",
  "data": {
    "build_id": "665f1f77bcf86cd799439011"
  }
}

List project builds

GET /v1/project/:id/github/builds

Rate limit: 50 per minute (counted per source IP).

Query

Response

{
  "status": "success",
  "message": "builds listed successfully",
  "data": [
    {
      "id": "665f1f77bcf86cd799439011",
      "commit_sha": "abc123def456789012345678901234567890abcd",
      "branch": "main",
      "status": "failed",
      "started_at": "2026-06-03T14:10:00.000Z",
      "finished_at": "2026-06-03T14:11:09.000Z",
      "error_code": "NPM_LOCKFILE_REQUIRED",
      "error_message": "O package-lock.json não foi encontrado no diretório raiz da aplicação.",
      "triggered_by": "manual",
      "created_at": "2026-06-03T14:10:00.000Z",
      "updated_at": "2026-06-03T14:11:09.000Z"
    }
  ],
  "pagination": {
    "total": 12,
    "page": 1,
    "limit": 10
  }
}

Get a specific build

GET /v1/project/:id/github/builds/:buildId

Rate limit: 50 per minute (counted per source IP).

Response

{
  "status": "success",
  "message": "build retrieved successfully",
  "data": {
    "id": "665f1f77bcf86cd799439011",
    "commit_sha": "abc123def456789012345678901234567890abcd",
    "branch": "main",
    "status": "failed",
    "started_at": "2026-06-03T14:10:00.000Z",
    "finished_at": "2026-06-03T14:11:09.000Z",
    "error_code": "NPM_LOCKFILE_REQUIRED",
    "error_message": "O package-lock.json não foi encontrado no diretório raiz da aplicação.",
    "triggered_by": "manual",
    "created_at": "2026-06-03T14:10:00.000Z",
    "updated_at": "2026-06-03T14:10:00.000Z"
  }
}

Failure fields

The codes below document GitHub compatibility routes. Neutral routes may add generic build codes; clients should keep error_message as a fallback.

List and detail responses can include these fields when a build fails:

Legacy builds may not have an error_code. API clients should use error_message as the fallback when error_code is absent or unrecognized. The text and language of error_message are not a stable localization contract; clients should prefer error_code for their own localized presentation.

The supported codes are:

diagnosis_status and diagnosis_code are kept for compatibility. Use error_code and error_message to present the failure cause.

For lockfile fixes and Node.js command validation, see Node.js dependencies.

Get incremental build logs

GET /v1/project/:id/github/builds/:buildId/logs

Rate limit: 200 per minute (counted per source IP).

Query

Response

{
  "status": "success",
  "message": "build logs retrieved successfully",
  "data": {
    "logs": [
      {
        "sequence": 1,
        "timestamp": "2026-06-03T14:10:01.000Z",
        "level": "info",
        "step": "build",
        "message": "npm ci",
        "final": false
      }
    ],
    "next_cursor": 1,
    "status": "building",
    "finished": false,
    "truncated": false
  }
}

Use next_cursor in the next request to fetch only new lines.

How to interpret it

Retention

GitHub build history is retained for up to:

• 30 builds per project
• 30 days of age

Whichever limit comes first removes the oldest records, together with their log chunks.

Polling example

curl -X GET "https://api.zenifra.com/v1/project/507f1f77bcf86cd799439011/github/builds/665f1f77bcf86cd799439011/logs?cursor=0&limit=200" \
  -H "x-api-key: your-api-key" \
  -H "x-organization-id: your-organization-id"

Next steps

• Metrics and Logs
• Deployments
• Zenifra CLI