Pipeline Failure Explainer

Inspiration

Developers lose a lot of time when a merge request pipeline fails. The actual failure is often buried across multiple jobs, logs, and CI configuration files, and the next fix is not immediately obvious. We wanted to build something that removes this friction directly inside GitLab.

What it does

Pipeline Failure Explainer is a GitLab Duo custom flow built for the Software Development Lifecycle. When triggered from a merge request, it analyzes the latest failed pipeline, reads the most relevant job logs, inspects related files like .gitlab-ci.yml and the flow definition, and produces a structured diagnosis.

The flow identifies:

the failing jobs
the likely root cause
supporting evidence from logs
the fastest next fix

In our demo, the flow was triggered from a merge request comment, collected pipeline/job context, analyzed the validation failure, and generated a remediation plan while creating follow-up branch activity.

How we built it

We built the project as a GitLab Duo custom flow using the GitLab AI Hackathon participant project template. The core implementation lives in flows/flow.yml and uses GitLab-native tools such as:

get_merge_request
get_pipeline_errors
get_pipeline_failing_jobs
get_job_logs
get_repository_file
list_repository_tree
create_merge_request_note

We published the flow in the GitLab AI Hackathon participant project, enabled it in the project, tagged a public version, and tested it on a demo merge request with an intentionally broken flow validation pipeline.

Challenges we ran into

The main challenge was understanding the exact behavior of the GitLab Duo runtime in the hackathon environment. We had to adapt to the participant template structure, publish the flow in the expected catalog format, and debug runtime/session behavior inside GitLab. We also adjusted our demo setup to create a reliable failed pipeline that the flow could inspect.

Accomplishments that we're proud of

We successfully built and published a real GitLab Duo custom flow that:

is triggered from a merge request
reads real GitLab pipeline and merge request context
performs direct analysis beyond simple chat
produces actionable debugging output inside GitLab

What we learned

We learned how GitLab Duo custom flows are structured, how the GitLab AI Hackathon template validates flows, how the AI catalog and bot identity work, and how to design a practical SDLC-focused agent experience under time pressure.