buildkite / buildkite/cli

💡 feat: one-call build failure summary, matching the MCP server's get_build_failure_summary

Open
#963 1 comment 0 reactions 0 assignees View on GitHub
Dominant language
Go
Stars
207
Forks
70
Avg merge
1d 18h
Merged PRs (30d)
24

Description

### Is your feature request related to a problem?

Diagnosing a failed build from the CLI takes N+2 commands and manual stitching:

1. `bk build view -p -s failed` to find which jobs failed
2. `bk job log --agent --max-tokens ...` once per failed job
3. nothing for annotations, because there is no annotation command (#962)

The official MCP server answers the same question in one call. Its
`get_build_failure_summary` returns build state, a tally of jobs by state, the terminal
problem jobs, bounded log tails for each, error and warning annotations, and failed Test
Engine executions — deliberately size-bounded, and documented as the tool to start with
before reaching for individual job, log, or annotation tools.

That design decision looks right, and there is no reason it should be MCP-only. Not every
consumer of the CLI can run an MCP server — CI scripts, shell pipelines, and coding agents
that only have shell access all end up hand-rolling the N+2 sequence above.

This is the use case behind #519, which was closed as completed with "output defaults to JSON,
so filter with jq". `-s/--job-states` did land and does help. But `jq` cannot fetch the log
tails, cannot fetch the annotations, and cannot apply a token budget across the result — the
expensive parts are the extra round trips, not the filtering. @mcncl invited a reopen on that
issue if the JSON answer did not fit the use case; this is that follow-up, filed separately
because the ask is an aggregate command rather than a filter.

### Describe the solution you'd like.

`bk build view --failure-summary` (or a `bk build failures ` subcommand), returning in
one call:

- build state, and a count of jobs by state
- the failed, timed-out, and cancelled jobs
- a bounded log tail per failed job, reusing the existing `--agent` windowing
- error and warning annotations
- failed Test Engine executions where the build has them

Honouring `--max-tokens` across the whole aggregate matters more here than on any single job
log, since the point is to hand a whole build's failure to something with a context budget.

### Describe alternatives you've considered.

Scripting the N+2 sequence. It works, and it is what everyone is doing, but each caller
re-derives the same bounding heuristics — how many log lines, which job states count as
terminal, how to spend a token budget across several failed jobs. The MCP server already made
those choices; the CLI implementing them once is strictly better than every caller guessing.

### Additional context

Version `bk 3.55.0`. Related: #519 (closed), #962 (annotations).

Contributor guide

Open the contributing guide

Research direction

Start by reading the existing `bk build view` and `bk job log` entry points, then compare their behavior with the MCP server's `get_build_failure_summary`; issue #962 covers annotations. Done means one CLI call returns build state, job counts, terminal problem jobs, bounded log tails, annotations, failed Test Engine executions, and honors `--max-tokens` across the aggregate.

Written by the indexing model from the issue text.

Assessment

Tech stack
go
Domain
cli
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Active
Clarity
Mostly clear
Newbie friendliness
45/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.