Builds GitHub
Use estes endpoints para disparar builds GitHub manualmente, listar o histórico, consultar um build específico e ler logs incrementais do pipeline.
Estes logs são diferentes de
GET /project/:id/logs.GET /project/:id/logsretorna logs da aplicação em execução; os endpoints abaixo retornam logs do pipeline de build GitHub.
Disparar build manual
POST /project/:id/github/deployBody
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
branch | string | Não | Branch a ser usada no build. Quando omitida, a API usa a branch configurada no projeto |
commit_sha | string | Não | Commit específico para disparar a build |
Resposta
{
"status": "success",
"message": "Build triggered successfully",
"data": {
"build_id": "665f1f77bcf86cd799439011"
}
}Listar builds do projeto
GET /project/:id/github/buildsQuery
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
page | number | Não | Página atual. Default 1 |
limit | number | Não | Tamanho da página. Default 10, máximo 50 |
branch | string | Não | Filtra por branch |
status | string | Não | Filtra por pending, building, success ou failed |
Resposta
{
"status": "success",
"message": "builds listed successfully",
"data": [
{
"id": "665f1f77bcf86cd799439011",
"commit_sha": "abc123def456789012345678901234567890abcd",
"branch": "main",
"status": "success",
"started_at": "2026-06-03T14:10:00.000Z",
"finished_at": "2026-06-03T14:11:09.000Z",
"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
}
}Obter um build específico
GET /project/:id/github/builds/:buildIdResposta
{
"status": "success",
"message": "build retrieved successfully",
"data": {
"id": "665f1f77bcf86cd799439011",
"commit_sha": "abc123def456789012345678901234567890abcd",
"branch": "main",
"status": "pending",
"triggered_by": "manual",
"created_at": "2026-06-03T14:10:00.000Z",
"updated_at": "2026-06-03T14:10:00.000Z"
}
}Obter logs incrementais do build
GET /project/:id/github/builds/:buildId/logsQuery
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
cursor | number | Não | Última sequência já consumida. Default 0 |
limit | number | Não | Quantidade máxima de chunks. Default 200, máximo 500 |
Resposta
{
"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 na próxima chamada para buscar apenas novas linhas.
Como interpretar
| Campo | Descrição |
|---|---|
logs | Lista incremental de linhas públicas do build |
next_cursor | Última sequência retornada |
status | Estado atual do build |
finished | true quando o build terminou com success ou failed |
truncated | true quando o log público foi truncado para proteger a estabilidade da plataforma |
Retenção
O histórico de builds GitHub é mantido por até:
- 30 builds por projeto
- 30 dias de idade
O que vencer primeiro remove os registros mais antigos, junto com os chunks de log associados.
Exemplo de polling
curl -X GET "https://api.zenifra.com/v1/project/507f1f77bcf86cd799439011/github/builds/665f1f77bcf86cd799439011/logs?cursor=0&limit=200" \
-H "x-api-key: sua-api-key" \
-H "x-organization-id: sua-organization-id"