Post failed GitLab pipelines to Telegram
A GitLab + Telegram agent flow
A merge lands on main, the pipeline goes red, and the person who broke the build is three tabs deep in something else. By the time anyone notices the failed deploy, the next commit has already stacked on top of a broken trunk. This recipe gives the team a louder signal than a GitLab email nobody reads: your agent lists recent pipelines, keeps the ones that failed, and posts a line to the Telegram chat the team watches all day. It calls manage_pipeline in list mode for the project and branch you name, compares the run IDs and statuses against what it saw last time, and for each newly-failed pipeline writes the branch, the commit, and the pipeline URL with send_message. GitLab answers when asked, it doesn't push, so you run this on a cadence, tight during release windows and looser overnight.
The flow
manage_pipelineManages CI/CD pipelines in a project: list, create, retry, cancel, or delete a pipeline.
send_messageSends a text message to a chat.
Step by step
- Name the project and branch to watch
Give the agent the GitLab project and the branch that matters, usually main or a release branch. It will list pipelines for that ref so feature-branch noise stays out of the chat.
- List pipelines and find the failures
The agent calls manage_pipeline in list mode and reads back each pipeline's status. It keeps only the ones in a failed state and ignores running or successful runs.
- Diff against the last run
Compare the current failed pipeline IDs to the set posted on the previous pass. Only IDs that weren't there before are new, so a pipeline that's been red for an hour isn't re-announced every cycle.
- Post the new red builds
For each newly-failed pipeline, call send_message to the chat ID you set with a short line: the branch, the short commit SHA, who triggered the pipeline, and the pipeline link to open in GitLab.
Tell your agent
Every five minutes, list the latest pipelines for the main branch of acme/api in GitLab. For any pipeline that newly entered a failed state since your last check, send a Telegram message to chat -1002233445566 with the branch, the commit SHA, who triggered the pipeline, and the pipeline URL. Don't repost failures you already announced.
Setup
This flow needs both servers connected to your agent. Follow each install guide:
Worth knowing
- send_message takes a numeric Telegram chat ID, not a group name. Resolve your group or channel to its ID once and pass it in; the telegram server drives a real user account, so it can only post to chats that account already belongs to.
- manage_pipeline returns pipeline status, not job-level detail. If you want to know which stage failed, the agent has to follow up with get_pipeline_jobs on that pipeline ID before it writes the message.
- A pipeline can flip from running to failed between passes, so key your dedupe on the pipeline ID plus its current status, not the ID alone, or a retried-then-failed run can slip through silently.
Questions
- Does it message the moment a build breaks?
- No. GitLab responds to the agent's call, it doesn't notify Telegram on its own. The chat lags real time by your polling interval, so shorten the cadence during a deploy if you want it closer to live.
- Will it spam the chat while a build stays broken?
- Not if you dedupe. The agent remembers the failed pipeline IDs it already posted and only messages on a new failure, so one red pipeline produces one alert, not one per cycle.
- Can it watch more than one branch?
- Yes. List pipelines per ref and post each with its branch name in the message. Keep the branches few and meaningful, since every extra ref is another round of polling and another source of chat noise.