Getting PR Workflow Results

Overview

Get workflow job results and provide commands to retrieve logs, without loading logs into main context.

Core principle: Return job summaries + retrieval commands, not actual logs. Let main agent decide what to fetch.

Automatic dependency: This skill automatically waits for workflows to complete before fetching results.

CRITICAL: Scope Guardrails

This skill reports workflow status with error details. It NEVER fixes issues.

When you find failures:

• ✅ Report which jobs failed
• ✅ Extract actual error messages and test failures from logs
• ✅ Include context (what operation was in progress when it failed)
• ✅ Provide commands to retrieve full logs for deeper investigation
• ✅ Suggest grep patterns to search logs
• ❌ DO NOT investigate root causes beyond what's in the error messages
• ❌ DO NOT propose fixes
• ❌ DO NOT make any code changes

Why: This skill runs in a subagent to save tokens. It extracts actionable error information but doesn't try to fix anything. Return the error details and let the caller decide what to do.

When to Use

Use when you need:

• Summary of which jobs passed/failed
• Commands to retrieve specific job logs
• Suggestions for searching logs (grep patterns)

When NOT to use:

• Need to actually read logs (use returned commands in main context)

Workflow

Step 0: Wait for Workflows to Complete (Automatic)

Before fetching results, ensure all workflows are complete by following the awaiting-pr-workflows skill.

Skill location: ~/.claude/skills/awaiting-pr-workflows/SKILL.md

Read and execute that skill's workflow to:

• Check for unpushed commits
• Verify PR exists and commit correlation
• Wait for workflows to start (up to 30s)
• Wait for workflows to complete (up to 20 minutes)

Once all workflows are complete, proceed to Step 1 below.

Step 1: Get Workflow Runs for PR Commit

# Get PR's head commit
PR_COMMIT=$(gh pr view $PR_NUM --json headRefOid -q '.headRefOid')

# List workflow runs for that commit
gh run list --commit $PR_COMMIT --json databaseId,name,status,conclusion,workflowName,createdAt

Step 2: For Each Run, Get Job Details

RUN_ID=<from step 1>

# Get jobs in this run
gh run view $RUN_ID --json jobs --jq '.jobs[] | {
  name: .name,
  conclusion: .conclusion,
  url: .html_url,
  steps: [.steps[] | select(.conclusion == "failure") | .name]
}'

Step 3: Check for Artifacts

Check if the run has artifacts that might help with debugging:

# List artifacts for this run
gh run view $RUN_ID --json artifacts --jq '.artifacts[] | {
  name: .name,
  size: .size_in_bytes,
  expired: .expired
}'

Common useful artifacts:

• Test reports (JUnit XML, HTML reports)
• Screenshots (for UI test failures)
• Crash logs
• Coverage reports
• Build artifacts

Step 4: Extract Error Messages from Failed Jobs

For failed jobs, retrieve the logs and extract key errors:

# Get failed logs
LOGS=$(gh run view $RUN_ID --log-failed)

# Extract pertinent errors (examples):
# - Test failures: grep for "FAILED", "✗", test names
# - Build errors: grep for "error:", "fatal:", compiler messages
# - Lint errors: grep for "warning:", "expected", actual vs expected
# - Runtime errors: grep for "Exception", "Error:", stack traces

What to extract:

• Specific test names that failed
• Error messages (first few lines of stack traces, not full traces)
• What operation was in progress (e.g., "compiling", "running test X")
• Exit codes if non-zero

What NOT to extract:

• Full logs (too verbose)
• Debug output
• Passing tests

Step 5: Build Return Summary

For each job, return:

1. Job name and result
2. Actual error messages/failures (extracted from logs)
3. Context (what was happening when it failed)
4. Artifacts (if any exist for the run)
5. Location in repo (workflow file path + line if applicable)
6. gh commands to retrieve full logs and download artifacts
7. grep suggestions for common issues

Return Format

PR #{number} Workflow Results (commit {sha}):

## ✅ Passing Jobs (N)
- Backend Tests
- iOS Lint
- workstation-test-e2e

## ❌ Failing Jobs (N)

### 1. iOS Test (failed after 7m28s)
**Workflow:** `.github/workflows/ci.yml:45`

**Errors found:**

testHealthCheckE2E FAILED Error: Timeout waiting for health endpoint after 30s at HealthCheckTests.swift:142

testSettingsE2E FAILED Error: Element not found: settingsButton at SettingsTests.swift:87

**Artifacts available:**
- `ios-test-results` (2.4 MB) - Test result bundle with screenshots
- `test-logs` (156 KB) - Detailed test logs

**Download artifacts:**
```bash
# Download all artifacts from this run:
gh run download 19727163744

# Download specific artifact:
gh run download 19727163744 -n ios-test-results

# Or view/download from web:
# https://github.com/{owner}/{repo}/actions/runs/19727163744

Retrieve full logs:

gh run view 19727163744 --log-failed
# OR specific job:
gh run view 19727163744 --job 56520688201 --log

Search suggestions:

# Find all errors:
gh run view 19727163744 --log | grep -i error

# Find test failures:
gh run view 19727163744 --log | grep -E "(FAILED|failed|✗)"

# Find specific test:
gh run view 19727163744 --log | grep "testHealthCheckE2E"

2. workstation-lint (failed after 35s)

Workflow: .github/workflows/workstation-ci.yml:12

Errors found:

error: unused import in src/simulator.rs
  --> src/simulator.rs:5:5
   |
 5 | use std::collections::HashMap;
   |     ^^^^^^^^^^^^^^^^^^^^^^^^^

warning: variable does not need to be mutable
  --> src/main.rs:42:9

Artifacts available: None

Retrieve full logs:

gh run view 19727163743 --log-failed

Search suggestions:

# Find linting errors:
gh run view 19727163743 --log | grep -E "(error|warning)"

# Find formatting issues:
gh run view 19727163743 --log | grep "Diff in"

---

Summary: 2 failures, 7 passing All results: https://github.com/{owner}/{repo}/pull/{number}/checks

## Finding Workflow File Locations

**Method 1: Via gh API**
```bash
gh api repos/{owner}/{repo}/actions/workflows \
  --jq '.workflows[] | {name: .name, path: .path}'

Method 2: Local search

find .github/workflows -name "*.yml" -o -name "*.yaml"

Method 3: From run metadata

gh run view $RUN_ID --json workflowName,workflowDatabaseId
# Then map to file using gh api

Common Log Search Patterns

For Test Failures

grep -E "(FAILED|✗|Error:|Exception)"
grep -B 5 -A 10 "test.*failed"  # Context around failures
grep "exit code [1-9]"           # Non-zero exits

For Build Failures

grep -i "error:"
grep "fatal:"
grep "npm ERR!"
grep "cargo.*error"

For Lint Failures

grep "warning:"
grep "Diff in"
grep "expected.*found"

Example Implementation

#!/bin/bash
# Run in subagent

PR_NUM=$1
PR_COMMIT=$(gh pr view $PR_NUM --json headRefOid -q '.headRefOid')

# Get all runs for this commit
RUNS=$(gh run list --commit $PR_COMMIT --json databaseId,conclusion,name)

# For each run, get job details
echo "$RUNS" | jq -r '.[] | .databaseId' | while read RUN_ID; do
  gh run view $RUN_ID --json jobs --jq '.jobs[] | {
    name: .name,
    conclusion: .conclusion,
    url: .html_url
  }'
done

# Format and return (pseudo-code)
# - Group by passing/failing
# - Add gh commands for each
# - Add grep suggestions based on job type

Common Mistakes

Loading full logs into context

• Problem: Full logs can be 100k+ tokens
• Fix: Extract only pertinent errors/failures, provide commands for full logs

Not extracting actual error messages

• Problem: User gets "test failed" without knowing what failed or why
• Fix: Extract specific test names, error messages, and context from logs

Extracting too much log content

• Problem: Including full stack traces or debug output bloats the response
• Fix: First few lines of errors only, not full traces

Not providing grep patterns

• Problem: User has to figure out how to search full logs
• Fix: Include job-type-specific grep examples

Checking runs without commit correlation

• Problem: May return results for old commits
• Fix: Always use --commit $SHA flag

Quick Reference

Task	Command
List runs for commit	gh run list --commit $SHA
Get run details	gh run view $RUN_ID --json jobs
Get failed logs only	gh run view $RUN_ID --log-failed
Get specific job log	gh run view $RUN_ID --job $JOB_ID --log
List artifacts	gh run view $RUN_ID --json artifacts
Download all artifacts	gh run download $RUN_ID
Download specific artifact	gh run download $RUN_ID -n $ARTIFACT_NAME
List workflows	gh api repos/{owner}/{repo}/actions/workflows

Use Subagents

CRITICAL: Always run in subagent.

Use Task tool with subagent_type='general-purpose'.
Give them this skill and the PR number.
They return job summaries + commands.

Why: Prevents loading massive logs into main context. Main agent gets actionable commands instead.