Cloud Overview

BuildButler Cloud is a hosted analytics backend and frontend that receives build data from any CI system. All integrations — whether a CLI reporter or an org-level webhook — funnel data into the same REST API at https://api.buildbutler.dev.

Architecture

+------------------------------------------------------------------+
|                        CI Systems                                |
|                                                                  |
|  +---------+  +--------+  +--------+  +-----------+             |
|  | Jenkins |  | GitHub |  | GitLab |  | Buildkite |             |
|  +---------+  +--------+  +--------+  +-----------+             |
|                                                                  |
|  +----------+  +--------------+                                  |
|  | TeamCity |  | Azure DevOps |                                  |
|  +----------+  +--------------+                                  |
+------------------------------------------------------------------+
        |
        |  plugin / @buildbutler/ci CLI / org-level webhook
        v
+------------------------------------------------------------------+
|                  https://api.buildbutler.dev                     |
|                                                                  |
|    POST /ingest/builds          POST /ingest/agents              |
|    POST /ingest/pipeline-stages POST /ingest/build-logs          |
|    POST /ingest/tests           POST /ingest/security-reports    |
+------------------------------------------------------------------+
        |
        v
+------------------------------------------------------------------+
|                    BuildButler Dashboard                         |
|                  https://app.buildbutler.dev                     |
+------------------------------------------------------------------+

Authentication

Every ingest request must include your API key in the Authorization header:

Authorization: Bearer YOUR_BUILDBUTLER_API_KEY

Get your API key from Settings → API Keys in the BuildButler dashboard.

Ingest Endpoints

All endpoints accept application/json and return application/json.

Base URL: https://api.buildbutler.dev/ingest

`POST /ingest/builds`

Records a completed build. This is the primary record that all other data references.

{
  "jobName": "my-pipeline",
  "buildNumber": 42,
  "status": "success",
  "duration": 124000,
  "startedAt": "2024-01-15T10:00:00Z",
  "completedAt": "2024-01-15T10:02:04Z",
  "jenkinsInstanceId": "github.com/my-org/my-repo",
  "branch": "main",
  "commitSha": "abc123",
  "cause": "push",
  "source": "github-actions",
  "externalRunId": "550e8400-e29b-41d4-a716-446655440000"
}

Field	Type	Required	Notes
`jobName`	string	Yes	Pipeline/workflow/job name
`buildNumber`	integer	Yes	Build number
`status`	string	Yes	`success`, `failure`, `unstable`, `aborted`, `in_progress`
`duration`	integer	Yes	Duration in milliseconds
`startedAt`	string	Yes	ISO 8601 datetime
`completedAt`	string	Yes	ISO 8601 datetime
`jenkinsInstanceId`	string	Yes	Unique identifier for the CI server or repo
`branch`	string	No	Source branch
`commitSha`	string	No	Commit hash
`cause`	string	No	Trigger reason (e.g. `push`, `pull_request`, `schedule`)
`source`	string	No	CI system identifier (e.g. `github-actions`, `gitlab`, `buildkite`)
`externalRunId`	string (UUID)	No	Deterministic UUID for deduplication — same ID = upsert, not duplicate

Returns the stored build record including its id (UUID), which is required for subsequent /stages, /tests, and /build-logs calls.

`POST /ingest/pipeline-stages`

Records the stages (jobs/steps) that make up a build.

{
  "buildId": "550e8400-e29b-41d4-a716-446655440000",
  "stages": [
    {
      "stageName": "build",
      "stageOrder": 0,
      "status": "success",
      "duration": 45000
    },
    {
      "stageName": "test",
      "stageOrder": 1,
      "status": "failure",
      "duration": 79000
    }
  ]
}

Field	Type	Required	Notes
`buildId`	UUID	Yes	`id` returned by `/ingest/builds`
`stages[].stageName`	string	Yes	Stage/job/step name
`stages[].stageOrder`	integer	Yes	Order of execution (0-based)
`stages[].status`	string	Yes	`success`, `failure`, `unstable`, `aborted`, `in_progress`, `skipped`
`stages[].duration`	integer	Yes	Duration in milliseconds

`POST /ingest/tests`

Records JUnit-style test results linked to a build.

{
  "buildId": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Unit Tests",
  "totalCount": 120,
  "passCount": 118,
  "failCount": 2,
  "skipCount": 0,
  "duration": 34.5,
  "testCases": [
    {
      "className": "com.example.UserServiceTest",
      "testName": "testCreateUser",
      "status": "passed",
      "duration": 0.12
    }
  ]
}

`POST /ingest/agents`

Reports the current state of CI agents/runners, including queue data.

{
  "jenkinsInstanceId": "github.com/my-org",
  "agents": [
    {
      "name": "linux-runner-1",
      "status": "online",
      "os": "linux",
      "arch": "amd64",
      "executors": 2
    }
  ]
}

`POST /ingest/build-logs`

Uploads the full console log for a build. Stored in Cloudflare R2 and accessible from the build detail view.

`POST /ingest/security-reports`

Records security scan results (SAST, dependency vulnerabilities) linked to a build.

How CI integrations use the API

The @buildbutler/ci CLI package handles all of this automatically — it auto-detects the CI environment from env vars, collects the relevant data, and calls the ingest endpoints in the correct order.

For webhook integrations, the BuildButler webhook receiver (/webhooks/github, /webhooks/gitlab, etc.) translates the CI system's native payload format into ingest API calls internally.

Either way, you never call the ingest API directly — the CLI or webhook does it for you.

Integration method	Who calls the ingest API
`@buildbutler/ci` CLI	The CLI, running inside your CI job
Org-level webhook	BuildButler's webhook receiver
Jenkins plugin	The plugin, running inside the Jenkins agent

On this page