Smart Slack alerts for failed GitLab pipelines

Build an agent workflow that triages failing GitLab CI/CD pipelines into a single, useful Slack alert. The goal is to replace the raw, noisy GitLab pipeline-failed notification with one clean message that explains what broke, what likely caused it, and tags the person responsible.

Trigger: an incoming webhook from GitLab on the Pipeline Hook event (object_kind = "pipeline"). Only proceed when object_attributes.status is "failed". Configure the workflow so a user can register the webhook URL in GitLab project settings under Webhooks with the "Pipeline events" box checked.

Filter early: only fire on the project's default branch or a protected branch. The webhook payload includes object_attributes.ref and project.default_branch, and protected branch state can be confirmed via the GitLab API if needed. Personal feature branches must be ignored. If the branch is not eligible, stop and return without posting.

Once a failure is in scope, the agent should use the GitLab integration to gather context. Call Get a Single Pipeline on the project_id and pipeline_id from the webhook to confirm the current status, ref, sha, web_url, and failure_reason. Then call List Project Pipelines with ref=<failing branch>, status=success, order_by=updated_at, sort=desc to find the most recent successful pipeline on the same branch and capture its sha. Then call List Commits with ref_name set to the failing sha and since/until tuned so the response covers commits between the last green sha and the failing sha; pick the offending commit (typically the most recent one before the failure) and collect its short_id, title, author_name, and author_email.

Use the Slack Bot integration to map the commit author to a Slack user: call Look Up User by Email with the GitLab commit author_email. If a match is returned, use the Slack user id to build an @ mention. If no match, fall back to the author's plain name.

Then have the agent draft a short, plain-English summary (3 to 6 sentences max). It should say what broke (the project, the branch, the failing stage from the pipeline payload), the suspected cause based on the commit message and the diff between the failing sha and the last green sha, and a single next step. Keep it scannable; no marketing language, no long explanations.

Post the alert with the Slack Bot integration using Send a Message to a channel the user configures (for example #ci-alerts). The message should include: a header line like "CI failed on <project> / <branch>", the @ mention of the commit author (or plain name fallback), the failing stage, the commit short_id with its title, the plain-English summary, and a link to the pipeline web_url. Format with Slack mrkdwn or simple Block Kit, but keep it compact.

Configuration the user should be able to set when installing the workflow: the GitLab projects to watch (or "all connected projects"), the Slack channel for alerts, whether to also count specific named branches beyond default and protected, and whether to suppress repeat alerts on the same commit sha so retries do not double-ping.

Important constraints: do not attempt to read job traces or job logs. Our GitLab catalog does not expose a get-job-trace operation, so stay at the pipeline + commit level and reason from failure_reason, the failing stage name, the commit message, and the diff between this run and the last green run. If the agent cannot determine a likely cause, it should say so plainly rather than guessing.