CI Triage Agent

When your GitHub Actions pipeline fails, finding the root cause often requires reading logs, understanding context, and making a judgment call. An AI-powered CI triage agent can automate this 24/7.

What the agent does

The CI triage agent continuously monitors your CI runs and, when a build fails:

1. Reads CI logs — fetches GitHub Actions logs and parses error output
2. Analyzes context — reviews recent commits, PRs, and code changes
3. Generates a summary — writes a concise root-cause analysis with code snippets
4. Proposes a fix — suggests a concrete change or debugging step
5. Takes action — creates a GitHub issue, opens a PR draft, or comments on the original PR
6. Tracks resolution — updates the issue with fix status as PRs merge

Set it up

Prerequisites

• AACWorkflow workspace with an active agent (see Quickstart)
• GitHub integration enabled (Settings → Integrations)
• Agent has access to GitHub API (repo, actions scope)

Step 1: Create the CI triage agent

1. Go to Settings → Agents and click New Agent
2. Choose your runtime and provider (Claude Code, Codex, or similar)
3. Name it ci-triage or build-doctor
4. Open its config and add a skill or custom prompt:

Role: CI failure investigator
Task: When a GitHub Actions job fails:
1. Fetch the build log from the GitHub API
2. Parse error messages and stack traces
3. Check git diff of the failing commit
4. Summarize root cause in 2-3 bullet points
5. Propose a one-line fix or debugging command
6. Create a GitHub issue with label "ci-failure"
7. Link the issue to the originating PR

Context: Be concise. Focus on what broke, not what worked.

Step 2: Wire the trigger

Add a GitHub Actions workflow .github/workflows/notify-ci-triage.yml:

name: Notify CI Triage Agent

on:
  workflow_run:
    workflows: ["Build", "Test"]
    types: [completed]

jobs:
  notify:
    if: failure()
    runs-on: ubuntu-latest
    steps:
      - name: Trigger CI triage agent
        run: |
          curl -X POST https://aacworkflow.com/api/webhooks/ci-failed \
            -H "Authorization: Bearer ${{ secrets.AACWORKFLOW_TOKEN }}" \
            -H "Content-Type: application/json" \
            -d '{
              "workflow_run_id": "${{ github.run_id }}",
              "repository": "${{ github.repository }}",
              "branch": "${{ github.ref }}"
            }'

Replace the webhook URL with your AACWorkflow instance's endpoint (or use a Zapier/Make integration as an alternative).

Step 3: Assign the task

Assign a GitHub issue to the ci-triage agent with the label ci-failure. The agent wakes up and investigates.

Example outputs

Input: GitHub Actions job fails with "connection timeout" during database migration test.

Agent summary:

Root cause: Migration script timeout. The test pool only has 2 connections; parallel migrations exhaust the pool.

Fix: Increase DB_POOL_SIZE=5 in test environment.

PR drafted: #1437 with the fix. Test re-run requested.

Action taken: Creates issue #1436 "CI: DB pool exhaustion on migration tests", opens PR #1437 as draft, comments on original PR with summary.

Tips & best practices

• Label patterns — tag CI failures with consistent labels (ci-failure, ci-blocking, ci-flaky) so you can filter and prioritize
• Slack integration — pipe agent findings to a Slack channel for visibility across the team
• Retry on fix — once a fix is merged, have the agent re-trigger the CI job to confirm it passes
• Flaky test detection — if a test passes on retry, mark it as flaky and create a separate investigation task

Related guides

• Dependency Update Agent — similar automation for security updates
• Release Notes Agent — track what changed and why