Menu

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.

Sign in at buildkite.com and open Personal Settings, then API Access Tokens. Create a new token and give it a description that names where it will be used, for example Mattering Automations.
Under Organization Access, pick the organization this token will automate. A token created today reaches exactly one, and Buildkite preselects the organization you used most recently, so check it rather than accepting it: only legacy tokens made before August 2023 hold several, and they cannot take on more, which means automating a second organization takes a second token and a second Mattering credential. Buildkite no longer offers an all-organizations token, so an organization you leave unselected stays unreachable no matter what scopes the token has.
Set Token Expiry deliberately. Buildkite defaults it to seven days when the field is left unset, which is the quiet reason an integration that worked all week starts returning 401. Pick a duration that matches how often you will actually rotate this credential, and put that rotation somewhere you will see it.
Choose the scopes. The read scopes to tick are read_pipelines and read_builds for the pipeline, build, and job listing nodes, read_clusters for clusters and queues, read_teams for Buildkite: List Teams, read_user for Buildkite: Get Current User, and the matching read scopes the same form offers for agents, artifacts, and organizations. Add write_pipelines to create, update, archive, or delete pipelines, and write_builds to create, cancel, rebuild, retry, unblock, or annotate: annotations do sit under the build scopes rather than carrying their own. Jobs are where that stops being true, and three job nodes have their own scopes: Buildkite: Get Job Log Output needs read_build_logs, Buildkite: Delete Job Log Output needs write_build_logs, and Buildkite: Get Job Environment Variables needs read_job_env. That split is why a token that lists a build's jobs perfectly well still returns 403 on the log. Two more write scopes gate destructive nodes: write_agents for Buildkite: Stop Agent and write_artifacts for Buildkite: Delete Artifact.
Granting write_builds is granting the ability to spend money and machine time. Buildkite: Create Build, Buildkite: Rebuild Build, and Buildkite: Retry Job start real CI runs that execute whatever the pipeline's steps do, including deploys, and they cannot be undone once started. If your first workflows only read, create the token read-only and widen the scopes when you actually need to write.
The scope set and the organization the token belongs to are the two things behind almost every 403 on this integration. Whatever you pick here, Buildkite: Get Access Token can read it back later, so you never have to guess what the stored credential is allowed to do.
Copy the token. Buildkite shows the value once, on the page it appears on at creation, and documents that as the last time you will see it, so if you navigate away before pasting it into Mattering you have to create a replacement. Keep it somewhere safe until you have pasted it into Mattering, and treat it as a live credential for your CI: anyone holding it can act as you in the organization you granted.

Connect Buildkite to Mattering

In Mattering Automations, open Connectors and click Add Connector.
Choose Buildkite from the list.
Click Create new credential, paste the API access token, and save.
The credential is stored encrypted in Google Secret Manager and never appears in workflow logs.
Click Test Connection. Mattering calls Buildkite's access token endpoint, which every token can call regardless of which organization or scopes it was granted, so a success proves the credential itself. A 401 means the token is wrong, mistyped, or revoked. Note what this check does not prove: it says nothing about whether the token can reach a particular organization or write to it.
Click Connect. All 40 Buildkite nodes appear in your canvas palette.

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
Test Connection calls Buildkite's access token endpoint, which every token can call regardless of scopes, so it proves the credential exists and is live without proving what it may do. A 403 afterwards is nearly always a missing feature scope or the wrong organization. Run Buildkite: Get Access Token and read the scope list it returns: if write_pipelines or write_builds is absent the write nodes will keep failing, and if read_build_logs or read_job_env is absent the job log and job environment nodes will keep failing even though listing jobs works. Then check which organization the token belongs to, since a token created for a different one fails the same way and cannot be widened. Edit the token in Personal Settings, then API Access Tokens, or create a second token for the other organization, and re-run the node.
Every node returns 401 after working fine for weeks
The token is gone rather than wrong, and expiry is the first thing to suspect. Buildkite's Token Expiry field defaults to seven days when it is left unset, so a credential that worked for exactly a week and then stopped is usually expired rather than misconfigured. Run Buildkite: Get Access Token while you still can, or read the token in Buildkite, and check its expiry before changing anything else. Tokens can also be revoked by their owner, and this integration ships a node that revokes them: if an automation ran Buildkite: Revoke Access Token, the credential died the moment it did and every Buildkite node stopped at once. Either way the fix is the same: create a new API access token for the same organization with the same scopes and a deliberate expiry, update the credential in Connectors, and run Test Connection again.
A node returns 404 even though the id came straight from another node
This is the slug rule. Organizations and pipelines return both an id UUID and a slug, and only the slug works in a path, so copying the id produces a syntactically perfect URL that resolves to nothing. Builds have the same trap in a different shape: they are addressed by the per-pipeline build number, not by the build's id. Re-read the source payload and take data[].slug for organizations and pipelines from Buildkite: List Organizations and Buildkite: List Pipelines, and data[].number for builds from Buildkite: List Pipeline Builds. Jobs, agents, artifacts, clusters, queues, teams, and users are the resources where the UUID is correct.
The job picker is empty, or a loop over jobs gets nothing
Two causes, and the second is the common one. First, the job picker is build-scoped, so it stays locked until an organization, a pipeline, and a build number are all chosen above it. Second, Buildkite: List Jobs is the connector's only cursor paginated lister and it wraps its result, so the rows are at data.items and the next page at data.links.next while every other Buildkite lister returns a bare array. A template written as data[0].id against this node reads nothing and fails silently at HTTP 200. Point the path at data.items and the loop fills.
Requests start failing with 429
Buildkite documents a default of 200 requests per minute per organization, adding that the default can vary by plan, plus 50 requests per minute per user. It reports both budgets in RateLimit response headers and answers a breach with 429 carrying a scope field that names which of the two limits was hit: rest for the organization limit, rest_user for the per-user one. Read that field before changing anything, because the fixes differ: a per-user breach usually means one workflow polling too hard, and a per-organization breach means the whole organization's traffic. Polling is the usual culprit. Widen the interval on build polls, or stop polling and let a Buildkite webhook deliver the finished event to a Mattering webhook trigger so the workflow runs once, when there is something to do.
An automation started a deploy nobody asked for
Create Build, Rebuild Build, and Retry Job run the pipeline's real steps, so if a step deploys, running the node deploys. There is no dry-run mode in the API to hide behind. Buildkite: Cancel Build stops a build that is still scheduled or running, and it is the first thing to reach for; cancelling one that already finished changes nothing. To prevent a repeat, put a condition on the branch or the build state ahead of the node, gate it behind an approval task rather than a bare trigger, and consider a token whose scopes stop at read for the workflows that only need to look. Buildkite: Get Access Token tells you which scopes the current credential holds.
Stopping an agent cancelled a running build
That is Buildkite's documented default rather than a bug in the node. The force parameter on Buildkite: Stop Agent defaults to true, which cancels the job the agent is currently running and the build that job belongs to, and that work is lost and cannot be resumed. Set force to false for a graceful drain: the agent finishes its current job and then disconnects. The node description says so, and this is the reason it is classed destructive rather than a routine write.
List Teams comes back empty on an organization that has teams
Two conditions have to hold. The token needs the read_teams scope, which is separate from the pipeline and build scopes and is easy to leave unchecked when creating the token, and Teams has to be turned on for the organization: an organization administrator enables it under Organization Settings, then Teams, and until that happens the organization simply has no teams for the node to return. Run Buildkite: Get Access Token to confirm the scope, then check the organization in Buildkite. The reason this node exists at all is the teams field on Buildkite: Create Pipeline and Buildkite: Update Pipeline, which takes an array of team UUIDs, so if those ids are all you need, Buildkite: List Teams is the node that supplies them.
Get Artifact Download URL returned a URL instead of the file
That is the design, and it is why the node is named for the URL rather than the download. Buildkite answers this endpoint with a 302 whose body carries a signed URL, and following that redirect would pull the artifact's bytes into the automation payload, which is the wrong place for a build's binary output. The node disables redirects, treats the 3xx as success, and hands back the signed URL at data.url for a later step to fetch, store, or pass to a person. Treat that URL as good for about 60 seconds, which is what Buildkite tells you to assume, so fetch it in the same run rather than passing it along to be opened later. The exception is an organization storing artifacts in its own S3 bucket, where the response is the standard public S3 URL for the object instead. Use Buildkite: List Build Artifacts or Buildkite: List Job Artifacts to find the artifact id in the first place.

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.

Start Free Explore our Products