gh-ci-artifacts

Download and parse GitHub Actions CI artifacts and logs for LLM analysis.

📖 Full Documentation →

Overview

gh-ci-artifacts automates the collection and normalization of GitHub Actions CI failures into structured JSON optimized for LLM analysis. It handles artifact downloads, log extraction, and parsing of common test/linter formats. Artifact type detection and validation is powered by artifact-detective, which identifies and validates 20+ test framework and linter output formats.

Key Features:

• Focuses on failures by default (skips successful runs)
• Zero-config operation with optional configuration file
• Automatic type detection for Playwright, Jest, pytest, JUnit, ESLint, and more
• HTML to JSON conversion for test reports
• Linter output extraction from logs
• Robust error handling with retry logic
• Resume functionality for incomplete downloads

Installation

Install globally:

npm install -g gh-ci-artifacts
gh-ci-artifacts 123

Or use with npx (no installation required):

npx gh-ci-artifacts 123

Requirements:

• Node.js 20+
• GitHub CLI (gh) installed and authenticated

Quick Start

# Download artifacts for a PR (from current repo)
npx gh-ci-artifacts 123

# Download artifacts for a branch
npx gh-ci-artifacts main

# Specify a different repository
npx gh-ci-artifacts 123 --repo owner/repo

# Resume interrupted download
npx gh-ci-artifacts 123 --resume

# Include successful runs (default: only failures/cancelled)
npx gh-ci-artifacts 123 --include-successes

# Wait for in-progress workflows to complete
npx gh-ci-artifacts 123 --wait

# Open HTML viewer in browser when complete
npx gh-ci-artifacts 123 --open

After downloading, open .gh-ci-artifacts/<ref>/index.html in your browser for an interactive file tree viewer (where <ref> is pr-<number> for PRs or branch-<remote>-<name> for branches).

Default Behavior:

• Only failed and cancelled runs are downloaded. Use --include-successes to download all runs.
• Only the latest retry attempt for each workflow is processed.

Configuration

Create .gh-ci-artifacts.json in your project directory:

{
  "outputDir": "./ci-artifacts",
  "maxRetries": 5,
  "skipArtifacts": [
    {
      "pattern": ".*-screenshots$",
      "reason": "Screenshots not needed for analysis"
    }
  ],
  "workflows": [
    {
      "workflow": "ci",
      "expectArtifacts": [
        {
          "pattern": "test-results",
          "required": true
        }
      ]
    }
  ]
}

See the Configuration Guide for all available options.

Output Structure

.gh-ci-artifacts/
└── pr-<number>/              # or branch-<remote>-<name>/
    ├── index.html            # Interactive HTML viewer
    ├── summary.json          # Master summary with all metadata
    ├── catalog.json          # Artifact catalog with type detection
    ├── artifacts.json        # Download inventory
    ├── raw/                  # Original downloaded artifacts
    ├── converted/            # Normalized artifacts (HTML/NDJSON/TXT → JSON)
    └── logs/                 # Extracted job logs (if applicable)

See the Output Format Guide for detailed schema documentation.

Supported Artifact Types

Supports 20+ artifact types including:

• Test Frameworks: Playwright, Jest, pytest, JUnit, Vitest, and more
• Linters & Formatters: ESLint, Prettier, Ruff, flake8, mypy, TypeScript (tsc), and more
• Coverage Reports: Coverage.py, JaCoCo, Nyc, and more

For a complete list, see the artifact-detective documentation.

Documentation

• Getting Started - Installation and setup
• CLI Reference - All command-line options
• Configuration Guide - Configuration options and examples
• Output Format - Understanding the results
• Features - Artifact detection, normalization, log extraction
• API Reference - Use as a library
• Architecture - How it works internally

Exit Codes

• 0 - Complete success (all artifacts downloaded)
• 1 - Partial success (some artifacts failed)
• 2 - Incomplete (workflows still in progress)

See Exit Codes Guide for details.

Use Cases

Claude Integration

After downloading artifacts, analyze failures with Claude using the structured JSON output. See the Claude Integration Guide for detailed examples and best practices.

Programmatic Usage

import { execSync } from "child_process";
import { readFileSync } from "fs";

// Download artifacts
execSync("npx gh-ci-artifacts 123", { stdio: "inherit" });

// Load summary for analysis
const summary = JSON.parse(
  readFileSync(".gh-ci-artifacts/pr-123/summary.json", "utf-8")
);

See the API Reference for library usage.

Limitations

• Artifacts expire after 90 days (GitHub limitation)
• Serial downloads to respect GitHub rate limits
• Branch mode only queries push event workflows
• Requires GitHub CLI (gh) to be authenticated

Contributing

Contributions welcome! Areas for improvement:

• Artifact type support - Contribute to artifact-detective for artifact detection improvements
• Performance optimizations - Improve download speed or processing efficiency
• Documentation - Help improve docs and examples

See the Contributing Guide for details.

License

MIT