Ellipse Gradient for Header

Buildkite Integration Guide

Connect Buildkite pipelines, builds, jobs, agents, and artifacts with enterprise systems through REST, GraphQL, webhooks, and orchestrated workflows.

Buildkite integration options at a glance

Buildkite provides a REST API for organizations, pipelines, builds, jobs, agents, teams, users, and artifacts, plus a GraphQL API for tailored queries and supported mutations. Selected pipeline, build, and job events can be delivered through outgoing webhooks, while builds and jobs execute asynchronously on Buildkite agents. Buildkite also supports artifact upload, listing, and download through its artifact interfaces. Martini can authenticate with bearer API tokens or applicable OAuth credentials, validate webhook signatures, orchestrate API calls, map Buildkite objects, transfer artifacts, and expose APIs for triggering or monitoring builds. Large synchronizations should use pagination, checkpoints, bounded concurrency, and reconciliation rather than assuming a general-purpose bulk API.

Integration pointSupported by Buildkite?Common use casesHow Martini supports it
REST APIsYesList and retrieve organizations, pipelines, builds, jobs, agents, teams, users, and artifacts; trigger, retry, cancel, or inspect builds and jobs where permitted.Martini can consume the Buildkite REST API from workflows, apply mappings and business rules, and expose reusable APIs around Buildkite operations.
GraphQL APIsYesRetrieve tailored fields and related Buildkite resources in a single query, and perform supported mutations.Martini can consume Buildkite GraphQL queries and mutations, with workflows limited to fields and operations confirmed in the current schema.
WebhooksLimitedReceive selected pipeline, build, job, and related lifecycle events such as starts, completions, failures, and blocked states.Martini can expose a webhook endpoint, validate the Buildkite signature, deduplicate deliveries, and retrieve authoritative resources after receiving an event.
Asynchronous build and job executionYesA request can trigger a build while jobs execute asynchronously on Buildkite agents.Martini can store the returned build identifier, return an asynchronous response, and monitor completion through webhooks or controlled polling.
File and artifact APIsYesList and download job artifacts such as test reports, packages, logs, coverage output, and deployment bundles.Martini can retrieve selected artifacts, transform metadata, transfer files to supported endpoints, and record duplicate-prevention checkpoints.
AuthenticationYesUse bearer API tokens with permissions, webhook signatures and shared secrets, or OAuth where delegated user access is required.Martini can store credentials in secure configuration, apply authorization headers, validate signatures, and separate environment-specific secrets.
Bulk APIsLimitedBuildkite's asynchronous execution model supports controlled batch-style processing, but a general-purpose bulk object API was not confirmed.Martini can paginate, checkpoint, reconcile, and use bounded concurrency instead of assuming a bulk endpoint.
Database accessNot confirmedNo customer-facing relational database connection was confirmed for Buildkite integration.Martini should use Buildkite APIs, webhooks, and artifact interfaces rather than relying on direct database access.

How Buildkite exposes data and business events

Buildkite REST APIs

Buildkite's REST API provides deterministic request and response operations for organizations, pipelines, builds, jobs, agents, teams, users, and artifacts. It is the principal mechanism for retrieving authoritative state and performing permitted actions such as triggering or retrying builds.

Martini implementation pattern

Martini implementation pattern: a workflow authenticates with a scoped bearer token, calls the required REST endpoint, handles pagination and response errors, maps the result to a canonical model, and writes it to a downstream system or returns it through a Martini API.

Implementation sequence

Authenticate with a scoped Buildkite bearer token
Retrieve the required pipeline, build, job, agent, or artifact resource
Follow pagination and persist synchronization checkpoints
Map Buildkite fields to the target model
Apply business rules and write the result
Store correlation data and handle retryable failures

Buildkite GraphQL API

Buildkite's GraphQL API supports tailored queries and supported mutations, which can reduce separate requests when related fields are needed. Query and mutation availability should be confirmed against the current schema.

Martini implementation pattern

Martini implementation pattern: a workflow sends a narrowly scoped GraphQL query or mutation, validates the response and possible errors, maps the selected fields, and falls back to REST or a controlled exception path when an operation is not available.

Implementation sequence

Authenticate the GraphQL request with a Buildkite API token
Submit a query containing only required fields
Validate data and GraphQL error responses
Map related pipeline, build, job, or artifact data
Apply operation-specific permissions and business rules
Persist the result and capture failures for retry or review

Buildkite webhooks

Buildkite supports outgoing webhook notifications for selected pipeline, build, job, and related events. Coverage is event-specific, and payloads may not contain the complete authoritative resource representation.

Martini implementation pattern

Martini implementation pattern: an exposed API endpoint receives the event, verifies the Buildkite signature, durably accepts and deduplicates the notification, then retrieves the current Buildkite resource before updating downstream systems. Out-of-order and repeated deliveries are expected.

Implementation sequence

Receive the Buildkite webhook notification
Validate the signature and shared secret
Persist an event or resource-based deduplication key
Retrieve the current build or job through the Buildkite API
Map the lifecycle state to the target system
Acknowledge accepted events and retry transient processing failures

Buildkite artifacts

Buildkite jobs can upload artifacts that integrations can list and download. Artifacts are suitable for reports, packages, logs, coverage output, deployment bundles, and generated documentation rather than arbitrary object attachments.

Martini implementation pattern

Martini implementation pattern: a workflow identifies eligible artifacts after a build event or scheduled reconciliation, downloads or streams them where practical, applies naming and retention rules, and transfers them to a supported storage or release endpoint.

Implementation sequence

Identify the completed Buildkite build and eligible artifacts
List artifact metadata through the Buildkite interface
Apply size, type, retention, and destination rules
Download or process the selected files
Transfer files to the target storage or release endpoint
Record artifact and destination identifiers to prevent duplicates

Common Buildkite integration patterns

Pattern 1: Synchronize Buildkite builds with ServiceNow

When to use this pattern

Use this pattern when failed or blocked CI/CD activity must create or update incidents, change records, or deployment records. Buildkite webhook events initiate processing, while the API supplies authoritative build and job state.

Integration direction
Buildkite
Martini
ServiceNow
Example Mapping
Buildkite FieldCanonical FieldTarget Field
build.idexternalExecutionIdu_buildkite_build_id
build.stateexecutionStatusstate
pipeline.slugpipelineNamecmdb_ci
build.web_urlsourceUrldescription
Martini implementation pattern

Martini validates the webhook signature, deduplicates the event, retrieves the current build and relevant jobs, and maps failed or blocked states to ServiceNow records. Business rules determine incident versus change handling, while correlation identifiers and retryable error handling prevent duplicate records.

Martini capabilities used
  • workflows
  • API consumption
  • webhook receiving
  • data mapping
  • business rules
  • error handling

Pattern 2: Publish Buildkite quality status to source control

When to use this pattern

Use this pattern when pull requests or merge requests need current Buildkite checks, job results, annotations, or test information before approval. The workflow should reconcile event data with the current Buildkite state.

Integration direction
Buildkite
Martini
GitHub
Example Mapping
Buildkite FieldCanonical FieldTarget Field
build.commitcommitShahead_sha
build.statequalityStatusstate
job.namecheckNamename
build.web_urldetailsUrldetails_url
Martini implementation pattern

Martini receives a selected Buildkite event, retrieves the build, jobs, annotations, and applicable test information, then maps the result to a GitHub check or pull-request status. Failed jobs can be included as review context, and retries use the build and commit correlation key.

Martini capabilities used
  • workflows
  • API consumption
  • data mapping
  • business rules
  • asynchronous orchestration
  • error handling

Pattern 3: Distribute Buildkite artifacts to release storage

When to use this pattern

Use this pattern when successful builds produce packages, test reports, logs, or deployment bundles that must be retained or made available in another repository or object store.

Integration direction
Buildkite
Martini
Amazon S3
Example Mapping
Buildkite FieldCanonical FieldTarget Field
build.idsourceBuildIdmetadata.build_id
artifact.pathartifactNameobject_key
artifact.download_urlsourceFileobject_body
build.commitsourceCommitmetadata.commit
Martini implementation pattern

A Martini workflow starts after a successful build event or reconciliation, lists eligible artifacts, filters by type and retention policy, and transfers selected files to S3. It records artifact identifiers and destination status, limits concurrency for large files, and retries transient transfer failures without duplicating completed transfers.

Martini capabilities used
  • workflows
  • API consumption
  • file handling
  • data mapping
  • business rules
  • retry handling

Pattern 4: Trigger and monitor Buildkite from an external process

When to use this pattern

Use this pattern when a release-management, service-management, or product application needs to request a Buildkite pipeline run and track its asynchronous outcome through a controlled API.

Integration direction
ServiceNow
Martini
Buildkite
Example Mapping
Buildkite FieldCanonical FieldTarget Field
request.pipelinepipelineSlugpipeline_slug
request.commitsourceCommitcommit
request.environmentexecutionEnvironmentenv
build.idexternalExecutionIdresponse.build_id
Martini implementation pattern

Martini exposes an authenticated API that validates the request, applies authorization and parameter rules, triggers the permitted Buildkite pipeline operation, and returns the build identifier. A follow-up workflow consumes webhooks or performs controlled polling, maps state transitions, and exposes status or a callback to the requesting system.

Martini capabilities used
  • API exposure
  • workflows
  • API consumption
  • authentication and authorization
  • data mapping
  • business rules
  • asynchronous execution

Applications commonly integrated with Buildkite

Buildkite commonly participates in source-control, release-management, incident-management, collaboration, and artifact-distribution architectures. Martini can coordinate these systems through Buildkite APIs and selected webhook events without requiring a dedicated native connector.

Application Scenario Direction Martini Pattern
GitHub Start pipelines from pull requests and synchronize commit, branch, check, and build status information. GitHub → Martini → Buildkite Martini receives or polls repository events, validates the requested pipeline action, triggers Buildkite through its API, and maps build and job outcomes back to GitHub checks or pull-request status.
GitLab Connect merge-request and repository activity to Buildkite pipelines and publish pipeline results back to GitLab. GitLab → Martini → Buildkite A Martini workflow consumes GitLab events or API data, applies branch and approval rules, triggers the appropriate Buildkite pipeline, and synchronizes the resulting status.
Bitbucket Run Buildkite pipelines for repository changes and return build status to pull requests. Bitbucket → Martini → Buildkite Martini maps Bitbucket repository and pull-request data to Buildkite trigger parameters, stores the returned build identifier, and updates Bitbucket after authoritative status retrieval.
Jira Link builds and deployment results to issues, releases, or development workflows. Buildkite → Martini → Jira Martini receives selected Buildkite events, retrieves the current build and job state, applies project and status rules, and updates Jira issues or release metadata.
ServiceNow Create or update incidents, change records, or deployment records when builds fail or releases progress. Buildkite → Martini → ServiceNow A signed Buildkite webhook starts a Martini workflow that deduplicates the event, retrieves authoritative details, and creates or updates the appropriate ServiceNow record.
Slack Notify engineering channels about failed, blocked, or completed builds and operational events. Buildkite → Martini → Slack Martini transforms Buildkite event data into channel-specific notifications, filters noisy states, and sends messages only after signature validation and event deduplication.
PagerDuty Create or resolve operational incidents when production-oriented pipelines fail or deployment gates are blocked. Buildkite → Martini → PagerDuty Martini maps qualifying Buildkite failures to PagerDuty incident actions, preserves correlation identifiers, and prevents duplicate incident creation during webhook retries.
Amazon S3 Store or retrieve build artifacts, reports, and release packages outside the Buildkite artifact lifecycle. Buildkite → Martini → Amazon S3 After a successful build, Martini lists and downloads selected Buildkite artifacts, applies naming and retention rules, and transfers them to S3 while recording artifact identifiers and transfer outcomes.

How to build a Buildkite integration in Martini

Objective

Establish authenticated access to Buildkite and the target systems while separating development, test, and production credentials.

Instructions in Martini

  • Configure a least-privilege Buildkite API token or applicable OAuth credentials
  • Store tokens and webhook secrets in secure Martini configuration
  • Configure target-system credentials separately by environment
  • Define authorized Buildkite organizations and pipelines

Objective

Select an event-driven, API-led, or scheduled trigger based on the required freshness and Buildkite event coverage.

Instructions in Martini

  • Use a Buildkite webhook for supported lifecycle events
  • Expose a Martini API for external build requests
  • Use a scheduler for reconciliation and checkpointed synchronization
  • Avoid continuous high-frequency polling of every job

Objective

Obtain the event envelope or current Buildkite resource and establish a reliable correlation key.

Instructions in Martini

  • Validate webhook signatures before processing
  • Retrieve authoritative builds or jobs when payloads are incomplete
  • Follow collection pagination
  • Persist event, build, job, or artifact identifiers for deduplication

Objective

Coordinate Buildkite calls, downstream calls, asynchronous status handling, and exception paths in a maintainable Martini workflow.

Instructions in Martini

  • Separate pipeline, build, and job lifecycle handling
  • Use bounded concurrency for large organizations
  • Route transient failures to retry handling
  • Use reconciliation when events arrive out of order or are missed

Objective

Convert Buildkite objects and lifecycle states into the target application's model without losing useful source identifiers.

Instructions in Martini

  • Map Buildkite identifiers, URLs, branches, commits, and states
  • Preserve build and job distinctions
  • Normalize timestamps and optional fields
  • Retain source correlation metadata for troubleshooting

Objective

Apply operational and business decisions before triggering builds, creating records, transferring artifacts, or publishing notifications.

Instructions in Martini

  • Distinguish failed, blocked, canceled, skipped, and passed states
  • Require authorized pipelines and approved parameters
  • Choose incident, change, notification, or release actions by policy
  • Prevent duplicate triggers and downstream updates

Common Buildkite data objects used in integrations

ObjectTypical UseCommon target systemsMartini handling
OrganizationsRepresent top-level Buildkite environments containing pipelines, teams, users, agents, and builds.ServiceNow, Jira, engineering dashboards, internal data storesMartini retrieves organization context, applies tenant or environment rules, and maps identifiers into a canonical integration model.
PipelinesDefine CI/CD processes, repositories, branches, steps, schedules, and notifications.GitHub, GitLab, Bitbucket, Jira, release-management systemsMartini synchronizes pipeline metadata, selects pipelines for orchestration, and applies branch, repository, and environment rules.
BuildsRepresent executions of a pipeline for a commit, branch, pull request, or manual trigger.GitHub, GitLab, Jira, ServiceNow, Slack, PagerDutyMartini uses webhook events as triggers, retrieves current build details, maps lifecycle states, and stores correlation and deduplication data.
JobsRepresent executable steps within a build, including command, wait, block, and trigger jobs.ITSM platforms, engineering dashboards, pull-request systems, monitoring toolsMartini models job-level state separately from build state and applies rules for failed, blocked, running, skipped, or completed jobs.
AgentsRepresent workers that execute Buildkite jobs, including agent metadata, queues, and status.Operations dashboards, capacity-management tools, alerting platformsMartini periodically retrieves agent data or processes relevant events, then maps status and queue information for operational reporting.
ArtifactsRepresent files uploaded by jobs, including test reports, packages, logs, coverage output, and deployment bundles.Amazon S3, release repositories, deployment platforms, internal file servicesMartini lists or downloads selected artifacts, applies transfer and retention rules, and records artifact identifiers and destination status.

Authentication and security considerations

Token and delegated authentication

Buildkite REST and GraphQL requests use API-token-based authentication, typically with bearer tokens and permissions determined by the token and user or organization access. OAuth is available when an application must act on behalf of Buildkite users.

Webhook validation

Buildkite webhook requests should be validated with the documented signature and shared secret before a Martini workflow accepts or acts on an event.

Least privilege and secrets

  • Use separate, least-privilege credentials for each environment and integration purpose.
  • Store API tokens, OAuth credentials, and webhook secrets in secure Martini configuration.
  • Restrict exposed endpoints and authorize build-triggering operations and parameters.

Operational considerations for Buildkite integrations

Rate limits and pagination

Respect Buildkite rate limits and response headers where supplied. Paginate collections and use checkpoints rather than assuming that one response contains all pipelines, builds, jobs, agents, or artifacts.

Events and idempotency

Webhook deliveries can be duplicated or arrive out of order. Persist an event, build, job, or artifact key, retrieve authoritative state when needed, and use a Martini-side deduplication record before triggering asynchronous builds or downstream actions.

Retries and concurrency

Retry transient failures and HTTP 429 responses with controlled backoff. Use bounded concurrency and avoid high-frequency polling, especially across large organizations.

State and schema changes

Model pipeline, build, and job lifecycles separately, including blocked, waiting, running, passed, failed, canceled, and skipped states. Treat webhook payloads as event envelopes, handle optional fields, and review GraphQL queries against schema changes.

Testing and artifacts

Test webhook signatures, duplicate delivery, out-of-order events, failed jobs, partial completion, and large artifact transfers. Record artifact identifiers and destination status to prevent duplicate transfers.

Why use Martini instead of scripts or point-to-point integrations?

Orchestration instead of isolated scripts

Martini centralizes Buildkite API calls, webhook handling, downstream updates, asynchronous status monitoring, and artifact transfers in versionable workflows rather than scattering logic across scripts.

Reusable integration behavior

Reusable workflows and exposed APIs can standardize authentication, correlation, validation, mapping, business rules, retries, and reconciliation across multiple Buildkite organizations or pipelines.

Controlled evolution

Martini separates vendor-specific Buildkite models from canonical downstream models. This makes it easier to accommodate optional fields, lifecycle differences, API changes, and new target systems without rebuilding point-to-point integrations.

Operational visibility

Centralized error handling, logs, checkpoints, and monitoring support troubleshooting of webhook delivery, rate limits, asynchronous execution, pagination, and artifact transfer failures.

Frequently asked questions

How can Buildkite be integrated with enterprise systems?

Buildkite can integrate through its REST API, GraphQL API, selected outgoing webhooks, asynchronous build and job execution model, and artifact interfaces. Enterprise workflows can retrieve or trigger builds, synchronize pipeline and job status, process artifacts, and publish results to downstream systems.

Can Martini integrate with Buildkite?

Yes. Martini can consume the Buildkite REST and GraphQL APIs, receive selected Buildkite webhook events, process artifacts, orchestrate asynchronous build monitoring, and expose APIs for downstream systems that need to trigger or query Buildkite.

Do I need a connector to integrate Buildkite with Martini?

No. A dedicated Buildkite connector is not required. Martini can use Buildkite's native REST and GraphQL APIs, selected webhooks, artifact interfaces, bearer-token authentication, webhook signatures, and applicable OAuth mechanisms.

Is there any extra Lonti cost to integrate Buildkite with Martini?

Lonti does not charge an additional per-connector or per-vendor fee to integrate Buildkite. The integration is subject to the provisioned capacity of the Martini environment. Separate costs may apply from Buildkite, cloud infrastructure, or other third-party systems based on subscriptions, usage, and deployment model.

Should a Buildkite integration use REST, GraphQL, or webhooks?

Use webhooks to initiate processing for supported events, then use REST or GraphQL to retrieve authoritative data or perform follow-up actions. REST is generally appropriate for documented individual operations, while GraphQL is useful for tailored related data. Event coverage and GraphQL mutation support should be checked for the required use case.

Can Martini receive Buildkite build notifications and synchronize status?

Yes. Martini can receive selected Buildkite pipeline, build, and job notifications through an exposed API endpoint or webhook workflow. It should validate signatures, handle duplicate and out-of-order delivery, retrieve current resources when necessary, and combine webhooks with periodic reconciliation for reliable synchronization.

Can Martini transfer Buildkite artifacts and handle data mapping?

Yes. Martini can list and download Buildkite job artifacts, map their metadata, and transfer selected files to supported storage, release, or internal file endpoints. Workflows can transform JSON and other payloads, apply retention and naming rules, and record artifact identifiers to prevent duplicate transfers.

Can Martini expose an API façade for Buildkite?

Yes. Martini can expose an authenticated API that validates business requests, triggers permitted Buildkite operations, returns a build identifier, and provides status or callback behavior for the asynchronous result. This can shield downstream applications from Buildkite-specific authentication, resource models, and retry logic.

Related Martini documentation

Buildkite APIs

Events

Workflows

Security

Operations

Connect Buildkite to your enterprise systems

Use Martini to orchestrate Buildkite APIs, selected webhook events, artifact transfers, and downstream workflows with secure configuration, data mapping, business rules, and operational controls.

EXPLORE MARTINI
BOOK A DEMO