Turn Buildkite build failures into tracked Jira bugs

When a Buildkite build finishes in a failed state, run this agent to open a tracked bug. Set the trigger as a Buildkite webhook subscribed to the build.finished event, and only act when the build state is failed (ignore passed, canceled, blocked, and skipped). Restrict the workflow to an allowlist of important pipelines and branches, for example the pipelines that gate production plus main and release branches, so failures on experimental or feature branches never generate tickets. If the failing build's pipeline or branch is not on the allowlist, stop and do nothing.

Using the pipeline slug and build number from the webhook payload, call Buildkite Get a Build to load the full context: the build state and message, the commit SHA, the branch, the author or creator, the build's web URL, and the list of jobs. Identify the job that failed (a failed state or a non-zero exit status) and call Buildkite Get a Job's Log Output to read that job's log. Concentrate on the tail of the log and any error output to work out the likely root cause.

Before filing anything, run Jira Search Issues (JQL) to check whether an open ticket already covers the same pipeline and branch. Search the target project for Bug issues that are not in a done or closed status and that reference this pipeline and branch, for example: project = ENG AND issuetype = Bug AND statusCategory != Done AND text ~ "<pipeline>" AND text ~ "<branch>". If a matching open ticket already exists, do not create a duplicate; stop there so a flapping pipeline never spawns repeat tickets.

Only when no open duplicate exists, call Jira Create Issue with issue type Bug in the chosen project. Draft a concise, useful ticket. Use a title that names the pipeline and the failing step or job, for example 'CI failure: web-deploy, RSpec step failed on main'. Write a short description that summarizes the likely root cause from the log, names the offending commit SHA and its author, states the branch, and includes a direct link to the Buildkite build. Keep it skimmable: one short root-cause paragraph plus the key facts (pipeline, branch, commit, author, build link). Do not paste the whole log; quote only the few relevant error lines.

If your team tracks work in Linear instead of Jira, the same flow applies: use Linear List Issues to look for an open duplicate for the pipeline and branch, then Linear Create Issue only when none exists. Keep the pipeline and branch allowlist easy to edit so the team can tune which failures are important enough to track.