Send failed Buildkite builds to a Telegram chat
A Buildkite + Telegram agent flow
Watch a small team's main pipeline and most builds are green, so the signal you want is the rare red one, ideally before it blocks a merge. The agent lists a pipeline's builds with list_builds, picks out the ones whose state came back failed, and sends each to a Telegram chat with send_message, carrying the pipeline, the build number, the branch, the commit message, and the build URL. Buildkite returns builds when the agent asks, never on its own, so the loop polls every few minutes and a build already reported is left alone.
The flow
list_buildsLists all builds for a pipeline with their status and commit information.
send_messageSends a text message to a chat.
Step by step
- Pick the pipeline and the chat
Give the agent the Buildkite organization and pipeline slug and the Telegram chat ID. Decide which states matter, typically failed, and whether you care about non-main branches.
- List recent builds
The agent calls list_builds for the pipeline and reads each build's state, number, branch, and commit, keeping the failed ones.
- Send the failures
For each new failed build it calls send_message to your chat with the pipeline, build number, branch, the commit subject, and the build URL so someone can open it directly.
- Remember the last build
Store the highest build number you've reported. On the next poll the agent only sends builds above it, so it won't repeat a failure it already announced.
Tell your agent
Every two minutes, list builds for the Buildkite pipeline acme/api on the main branch. Send any build in a failed state to Telegram chat -100333 with the build number, branch, commit message, and build URL. Track the last build number reported and don't resend ones already announced.
Setup
This flow needs both servers connected to your agent. Follow each install guide:
Worth knowing
- list_builds returns running and scheduled builds alongside finished ones. Filter on a terminal failed state, or the agent reports a build still in flight.
- send_message addresses a chat by numeric ID and needs the bot to be a member of the group. Resolve the ID once and confirm membership before the first send.
- For the failing step's output, get_job_logs returns a job's log. Link to the build in the message and let the agent fetch the log only on request, since full logs flood a chat.
Questions
- Can it cover several pipelines at once?
- Yes. The agent calls list_builds per pipeline slug and applies the same failed-state filter to each, posting to the same chat or a different one per pipeline as you prefer.
- Will it message me the instant a build breaks?
- No. Buildkite answers the agent's poll rather than pushing, so the message trails the failure by your interval. A two-minute loop is close enough for most merge gates.