Mattering Automations Buildkite integration
Connect Buildkite to Mattering Automations: pipelines with archive and unarchive, builds with create, cancel, and rebuild, jobs with retry, unblock, logs, and environment variables, agents, artifacts with signed download URLs, and build annotations as workflow steps, authenticated with one API access token.
The Mattering Automations Buildkite integration adds the Buildkite REST API v2 to your automation canvas: list and manage pipelines from creation through archive, unarchive, and delete, list builds across every organization or one pipeline and create, cancel, or rebuild them, work with jobs including retry, unblock, log output, and environment variables, read agents and stop them, list artifacts and get signed download URLs, read and write build annotations, and read organizations, members, teams, clusters, cluster queues, and emoji shortcodes.
The credential is a Buildkite API access token, created under Personal Settings, then API Access Tokens, and sent as an Authorization Bearer header on every request. Buildkite tokens are scoped twice over: a token you create today reaches exactly one organization, so automating a second one means a second token and a second Mattering credential, and it carries a read and write scope set chosen per feature, with a separate delete tier on a few surfaces this connector does not touch. That is the part worth slowing down for, because a valid token with the wrong scopes fails in a way that looks like a broken credential. The token also carries an expiry that defaults to seven days when it is left unset, which is the other setting to get right before anything depends on it. Setup takes a few minutes, and this guide walks through each step and ends with the full node reference.
Two behaviors shape everything else. Addressing is by slug and by build number: Buildkite payloads carry both an id UUID and a slug for organizations and pipelines, and only the slug works in a path, while a build is addressed by its per-pipeline number rather than its id. And some nodes cost real money and minutes. Create Build, Rebuild Build, and Retry Job start real CI work that runs whatever the pipeline's steps do, deploys included, while five nodes are flagged destructive: Revoke Access Token, Delete Pipeline, Delete Job Log Output, Delete Artifact, and Stop Agent. Each carries its warning on the node itself, and the sections below say where to put a gate.
Before you start
- A Buildkite account with access to at least one organization, and permission to create an API access token for it. Buildkite access tokens are personal, so the token belongs to a user and acts as that user.
- A Buildkite API access token for the organization you want to automate, carrying the scopes your nodes need. It is created under Personal Settings, then API Access Tokens, and the next section walks through the choices.
- At least one pipeline with build history to point the first reads at. An empty organization is workable too: Buildkite: Create Pipeline can stand one up, and it asks for a cluster id you can read with Buildkite: List Clusters.
- A Mattering workspace with access to the Automations app.
- Not required and deliberately not stored here: Buildkite agent tokens. Those mint the credential agents use to join a cluster, which is a different kind of secret with a different job, and this integration does not touch those endpoints at all.
Create a Buildkite API access token
Mattering authenticates to Buildkite with an API access token sent as an Authorization Bearer header to api.buildkite.com. Buildkite tokens are not all-access keys: when you create one you pick the single organization it may reach and the read and write scopes it carries per feature, with a separate delete tier on a few surfaces this integration does not touch, so you can hand this integration a read-only credential and widen it later. Choose deliberately, because the write scopes are what let a workflow start real CI runs.
Connect Buildkite to Mattering
Verify it works
Start with the credential health check. Drop Buildkite: Get Access Token on a canvas and run a test step with no configuration at all. It returns the token's uuid, description, creation date, expiry, owning user, and, most usefully, the scope list the credential actually carries. The token value itself is never echoed. Read that scope list now and compare it to the nodes you plan to use; it is the cheapest way to find a missing write_builds or read_clusters before a workflow depends on it.
Then walk the addressing chain, which is also the order the canvas pickers unlock in. Run Buildkite: List Organizations and copy the slug, not the id UUID in the same payload, because only the slug works in a path. Feed it to Buildkite: List Pipelines and copy a pipeline slug the same way. Feed that to Buildkite: List Pipeline Builds and note the build number, which is the per-pipeline counter rather than the build's id. From there Buildkite: List Jobs returns the build's steps, with one shape difference worth seeing once: this is the connector's only cursor paginated lister, so its rows sit at data.items rather than at the top level like every other Buildkite list. Everything in this path is read-only. It cannot start a build, spend a minute, or reach any of the five destructive nodes, so it is safe to re-run whenever you rotate the token.
Node reference
40 nodes, generated from the connector itself so this reference always matches what ships.
Read and query nodes 25
Buildkite: Get Access Token
buildkite_get_access_token
Check the stored API access token: returns its uuid, the SCOPE list it carries, its description, creation date and expiry, plus the owning user. Every token can call this regardless of scopes, so it is the credential health check to run first, and the scope list tells you up front whether a write node will be allowed. The token value itself is never echoed.
Buildkite: Get Agent
buildkite_get_agent
Fetch one agent by UUID: connection state, host details, version, queue, meta-data, the job it is running, and when it connected or was last seen.
Buildkite: Get Artifact Download URL
buildkite_get_artifact_download_url
Get a time-limited signed download URL for one artifact, returned at data.url with HTTP 302. The node deliberately does NOT follow the redirect: it hands back the URL so a later step can fetch the file, rather than pulling a binary into the automation payload. The URL expires, so use it promptly.
Buildkite: Get Build
buildkite_get_build
Fetch one build by its pipeline build NUMBER: state, branch, commit, message, creator, meta-data, timings and the full jobs array with each job's exit status and log URL. The natural node to poll while waiting on a build.
Buildkite: Get Current User
buildkite_get_user
Fetch the user the token belongs to: id, name, email and avatar. Requires the read_user scope. Useful for stamping which identity an automation is acting as.
Buildkite: Get Job
buildkite_get_job
Fetch one job by id: state, command, exit status, step key, agent, retry lineage and timings, plus the log and artifact URLs. Use it to poll a single long-running step.
Buildkite: Get Job Environment Variables
buildkite_get_job_env
Fetch the environment variables a job ran with, under data.env. Invaluable for debugging why one build behaved differently from another. NOTE: this returns whatever the job had in its environment, so if the pipeline injects secrets as plain environment variables they land in the automation's execution record.
Buildkite: Get Job Log Output
buildkite_get_job_log
Fetch a job's log as JSON: the log text at data.content, its size in bytes, and header timestamps. The node an automation reaches for when it wants to summarize or search a failure. Logs can be large, so expect a big payload on chatty steps.
Buildkite: Get Organization
buildkite_get_organization
Fetch one organization by slug: name, web URL, creation date, and the sub-resource URLs for its pipelines, agents and emojis.
Buildkite: Get Pipeline
buildkite_get_pipeline
Fetch one pipeline by slug: repository, default branch, YAML configuration, visibility, cluster, tags and archived state.
Buildkite: List Agents
buildkite_list_agents
List an organization's build agents with connection state, hostname, IP, version, queue, meta-data and the job each one is currently running. The capacity view: count connected agents against scheduled jobs to see whether CI is starved.
Buildkite: List All Builds
buildkite_list_builds
List builds across EVERY organization the token can see, newest first. The broadest read in the connector: good for a cross-organization dashboard, but set exclude_jobs when you only need state, because full build payloads with jobs are large.
Buildkite: List Build Annotations
buildkite_list_build_annotations
List the annotations attached to a build: the rendered HTML panels steps publish for coverage numbers, test summaries and links. This is where a build's own report lives, so it is the richest thing to forward into a chat message or a task.
Buildkite: List Build Artifacts
buildkite_list_build_artifacts
List every artifact uploaded by every job in a build, with path, filename, MIME type, size, SHA1 and the job that produced it. Filter by path with a glob to find one file across a large matrix build.
Buildkite: List Cluster Queues
buildkite_list_cluster_queues
List a cluster's queues with their key, description and dispatch state. dispatch_paused is the one to watch: a paused queue means jobs are piling up and no agent will pick them up, which looks identical to a capacity problem until you check.
Buildkite: List Clusters
buildkite_list_clusters
List an organization's clusters: the isolation boundary that groups agent queues and the pipelines allowed to use them. Each entry carries its default queue and the cluster UUID a pipeline needs at creation time.
Buildkite: List Emojis
buildkite_list_emojis
List the emoji shortcodes an organization can use, with their image URLs and any aliases, including custom emoji uploaded by the organization. Useful when rendering build messages or pipeline names elsewhere, since Buildkite stores shortcodes like :rocket: as literal text.
Buildkite: List Job Artifacts
buildkite_list_job_artifacts
List the artifacts one job uploaded, with path, size, MIME type, SHA1 and state. Narrower than the build-level lister when a matrix build produces the same filename from many jobs.
Buildkite: List Jobs
buildkite_list_jobs
List a build's jobs with their id, step key, state, command and timings. Unlike every other Buildkite lister this one is CURSOR paginated and wraps its rows: the array lives at data.items and the next page URL at data.links.next. Filter state to failed to find exactly what broke.
Buildkite: List Organization Builds
buildkite_list_organization_builds
List builds across all of one organization's pipelines, newest first, with the same filter set as the other build listers. This is the practical one for an organization-wide CI status feed: filter state to running or failed to see what needs attention.
Buildkite: List Organization Members
buildkite_list_organization_members
List the people in an organization with their user UUID, name, email, role (admin or member) and SSO mode. The ids here are the user UUIDs the build listers' creator filter and the teams lister's user_id filter expect.
Buildkite: List Organizations
buildkite_list_organizations
List the Buildkite organizations this token can access, each with the SLUG that every other node needs. Note the response carries both an id UUID and a slug: paths use the slug.
Buildkite: List Pipeline Builds
buildkite_list_pipeline_builds
List one pipeline's builds, newest first. Each entry carries the build NUMBER that every build action needs, plus state, branch, commit, message and timings. Filter by branch to answer questions like whether main is green.
Buildkite: List Pipelines
buildkite_list_pipelines
List an organization's pipelines with their SLUG, repository, default branch, visibility, archived state and live build and job counts. The running and scheduled counts make this a one-call CI health check.
Buildkite: List Teams
buildkite_list_teams
List an organization's teams with their UUID, name, slug, privacy and whether each is the default team. Requires the read_teams scope and only returns anything once Teams is enabled on the organization. The UUIDs here are what the pipeline nodes' teams field expects.
Action nodes 15
Buildkite: Archive Pipeline
buildkite_archive_pipeline
Archive a pipeline: it stops accepting new builds and drops out of the default pipeline list, while its history and artifacts are kept. This is the safe alternative to deleting a pipeline you no longer run, and Buildkite: Unarchive Pipeline puts it back.
Buildkite: Cancel Build
buildkite_cancel_build
Cancel a build that is scheduled or running. Its jobs stop, the build lands in the canceled state, and the record stays in history. Cancelling a build that already finished changes nothing. This is the stop button for anything Create Build or Rebuild started.
Buildkite: Create Build
buildkite_create_build
Start a new build on a pipeline at a given commit and branch. WARNING: this starts a REAL CI run. It consumes the organization's pipeline minutes, runs whatever the pipeline's steps do (including deploys), and cannot be undone. It is classed a reversible write only because it produces a build record that Buildkite: Cancel Build can stop while it is still running. Use the literal commit value HEAD to build the branch tip. Anything you pass in env and meta_data is visible to the build's steps, so never put secrets there.
Buildkite: Create Build Annotation
buildkite_create_build_annotation
Attach an annotation panel to a build, in Markdown or HTML. The way to write an automation's findings back onto the build page where the team already looks, for example a deploy summary or a link to a report. Reusing the same context replaces that panel, or appends to it when append is true.
Buildkite: Create Pipeline
buildkite_create_pipeline
Create a pipeline in an organization. Supply EITHER a YAML configuration string (the modern form) OR a visual steps array, along with name, repository and cluster_id. Creating a pipeline does not itself run anything; the first build starts when something triggers it. Reversible via Buildkite: Delete Pipeline, which is Destructive.
Buildkite: Delete Artifact
buildkite_delete_artifact
DESTRUCTIVE AND IRREVERSIBLE: permanently deletes an uploaded artifact. The stored file is gone and cannot be recovered; the artifact record moves to the deleted state. Used for purging large or sensitive build outputs. Returns 204 with no body.
Buildkite: Delete Job Log Output
buildkite_delete_job_log
DESTRUCTIVE AND IRREVERSIBLE: permanently deletes a job's log output. Buildkite keeps no copy and the job's own record stays but with no log to read. The legitimate use is purging a log that captured a secret; fetch it first if you need the content. Returns 204 with no body.
Buildkite: Delete Pipeline
buildkite_delete_pipeline
DESTRUCTIVE AND IRREVERSIBLE: permanently deletes a pipeline along with its build history, job logs and artifacts. There is no undo and no recycle bin. If you only want the pipeline to stop running, use Buildkite: Archive Pipeline instead, which keeps everything and can be reversed. Returns 204 with no body on success.
Buildkite: Rebuild Build
buildkite_rebuild_build
Re-run an existing build at the same commit, creating a NEW build whose rebuilt_from points at the original. WARNING: this starts a REAL CI run. It consumes the organization's pipeline minutes, runs whatever the pipeline's steps do (including deploys), and cannot be undone. It is classed a reversible write only because it produces a build record that Buildkite: Cancel Build can stop while it is still running. The pipeline must have rebuilds allowed. The classic retry a flaky build automation, and the classic way to accidentally redeploy, so gate it on the build's state.
Buildkite: Retry Job
buildkite_retry_job
Retry a single job inside a build, rescheduling that step rather than the whole build. WARNING: this runs REAL CI work and consumes pipeline minutes, and if the step deploys it will deploy again. Cheaper than a full rebuild when one flaky step failed. Only jobs in a retryable state can be retried.
Buildkite: Revoke Access Token
buildkite_revoke_access_token
DESTRUCTIVE AND IRREVERSIBLE: permanently revokes the API access token this connector is authenticated with. Every Buildkite node in every automation stops working immediately and a new token must be created in Buildkite and stored again. There is no undo and no confirmation step. Build this into a break-glass credential-rotation flow only.
Buildkite: Stop Agent
buildkite_stop_agent
DESTRUCTIVE BY DEFAULT: instructs an agent to disconnect. Buildkite's force parameter defaults to TRUE, which CANCELS the job the agent is currently running and the build that job belongs to; that work is lost and cannot be resumed. Set force to false to let the current job finish first, which is what a graceful drain wants. Returns 204 with no body.
Buildkite: Unarchive Pipeline
buildkite_unarchive_pipeline
Restore an archived pipeline so it accepts builds again and reappears in the pipeline list. Clears archived_at.
Buildkite: Unblock Job
buildkite_unblock_job
Release a block step so the build continues past a manual gate. This is how an approval flow in another system lets a Buildkite deploy proceed. Everything after the block step then runs, so treat it as authorizing that work. Supply fields when the block step declares input fields.
Buildkite: Update Pipeline
buildkite_update_pipeline
Update a pipeline. This is a PATCH, so only the fields you fill are changed and everything else is left alone. Note that configuration REPLACES the pipeline YAML wholesale, and changing slug changes the pipeline's URL, which breaks any automation still using the old one.
Using the integration
On the automation canvas
Buildkite nodes chain with every other node in Mattering. A scheduled sweep can run Buildkite: List Organization Builds filtered to the failed state and open one task per failure, a deploy workflow can wait on Buildkite: Get Build until the state settles and then post to chat, and Buildkite: List Pipelines returns live running and scheduled counts that make a one-call CI health tile. The values that flow between nodes are the organization slug, the pipeline slug, the build number, the job id, and the artifact id, in that order, and the config pickers unlock in the same sequence.
From AI assistants over MCP
Every node speaks MCP, the open protocol for connecting AI assistants to tools, so Claude, ChatGPT, and any MCP-capable assistant can drive this surface, with Matter using the same nodes natively inside the platform. The 25 query nodes are the surface to hand an agent first: Buildkite: Get Build, Buildkite: List Jobs, Buildkite: Get Job Log Output, and Buildkite: List Build Artifacts are enough to diagnose a failure in one conversation. Keep the run-starting and destructive nodes behind conditions or approval steps rather than in an agent's default reach.
Slugs, numbers, and the 404 that looks like a permissions error
Buildkite returns both an id UUID and a slug for organizations and pipelines, and paths accept only the slug. Builds are addressed by their per-pipeline number, so build 412 in one pipeline and build 412 in another are different builds. Pass a UUID where a slug belongs and the API answers 404 with a URL that looks perfectly reasonable. Jobs, agents, artifacts, clusters, queues, teams, and users are the ones that genuinely use UUIDs. Every field in this integration asks for the value that works and repeats the rule in its description, and Buildkite: List Organizations is where the first slug comes from.
The one lister that wraps its rows
Buildkite returns bare JSON almost everywhere: listers give a plain array, so downstream paths look like data[0].slug, and getters give a plain object, so data.state. Buildkite: List Jobs is the single exception. It is cursor paginated and wraps its result, putting the rows at data.items and the next page URL at data.links.next. This is the kind of difference that silently produces an empty picker or a blank template value, so when a job loop returns nothing, check which shape the path was written for before checking anything else.
The nodes that start real CI runs
Buildkite: Create Build starts a run at a branch and commit, accepting the literal value HEAD to build the branch tip, and Buildkite: Rebuild Build re-runs an existing build at the same commit as a new build. Buildkite: Retry Job reschedules one step instead of the whole pipeline. All three run whatever the pipeline's steps do, deploys included, taking up agent capacity and billing whatever compute those steps use. They are classed reversible writes only because Buildkite: Cancel Build can stop a run that is still going. Buildkite: Unblock Job belongs in the same conversation: it releases a manual gate, so everything after the block step runs and using it is authorizing that work. Two more honest notes carried on the nodes: what you pass in Create Build's env reaches every step in the build, and Buildkite says outright that build meta-data is not a secure medium and can be viewed through its interface, so nothing secret belongs in either field, and Buildkite: Get Job Environment Variables returns whatever the job had in its environment, so a pipeline that injects secrets as plain environment variables lands them in the automation's execution record.
The five destructive nodes, gated
Buildkite: Revoke Access Token is the sharpest, because it revokes the credential this integration runs on: every Buildkite node in every automation stops working immediately and a new token has to be created and stored. It exists for break-glass credential rotation, not for routine use. Buildkite: Delete Pipeline takes the pipeline's build history, job logs, and artifacts with it, and Buildkite documents no undo for it, which is exactly why Buildkite: Archive Pipeline and Buildkite: Unarchive Pipeline are built: archiving is the documented alternative that stops new builds and hides the pipeline while preserving its builds, build logs, and artifacts. Buildkite: Delete Job Log Output and Buildkite: Delete Artifact permanently destroy stored output, and their legitimate use is purging something that captured a secret, so fetch the content first if you still need it. Buildkite: Stop Agent is destructive by default: Buildkite's force parameter defaults to true, which cancels the job the agent is running and the build that job belongs to, so set force to false when you want a graceful drain.
Writing findings back onto the build
Annotations are where a build reports on itself, the rendered panels a pipeline publishes for coverage numbers, test summaries, and links, and they are the richest thing to read out of a build. Buildkite: List Build Annotations fetches them, and Buildkite: Create Build Annotation writes one in Markdown or HTML, which is how an automation puts its own findings, a deploy summary, a link to a report, a triage note, on the page the team already looks at. Reusing the same context value replaces that panel rather than stacking duplicates, or appends to it when append is set, so a workflow that runs repeatedly on the same build stays readable.
What stays off the canvas
Several Buildkite surfaces are deliberately excluded. Test Engine, Packages and Registries, Portals, Rules, and Pipeline Templates are separate product surfaces that deserve their own curation rather than a few token nodes on a CI connector. Audit events are a high volume compliance export. Agent tokens are excluded entirely, because those endpoints mint the credential agents use to join a cluster and that does not belong in a workflow. Team membership changes and team CRUD are left out as a footgun, though Buildkite: List Teams is built because the teams field on Buildkite: Create Pipeline and Buildkite: Update Pipeline takes an array of team UUIDs and this is the node that supplies them. Administrative configuration is also out: organization and pipeline settings, notification services, repository connections, and pipeline webhook setup are things a human configures once, not shapes a canvas should be reshaping.
Troubleshooting
Test Connection passes but a pipeline or build node returns 403
Every node returns 401 after working fine for weeks
A node returns 404 even though the id came straight from another node
The job picker is empty, or a loop over jobs gets nothing
Requests start failing with 429
An automation started a deploy nobody asked for
Stopping an agent cancelled a running build
List Teams comes back empty on an organization that has teams
Get Artifact Download URL returned a URL instead of the file
Related
The Buildkite MCP
What connecting Buildkite unlocks for AI agents and automations, with common uses and FAQs.
More guides
All Automations documentation
Every integration guide, plus how connectors, credentials, and workflows fit together.
Buildkite is a trademark of its respective owner. Mattering uses platform names to identify the services these integrations connect to; no endorsement or affiliation is implied.