gh-actions-parser 1.0.0

CLI tool to parse GitHub Actions run logs and extract structured failure information

gh-actions-parser

CLI tool to parse GitHub Actions run logs and extract structured failure information. Built for automated CI triage systems.

Features

• Multi-failure-type detection: Identifies test failures (pytest, Jest), build errors (TypeScript, npm), and linting errors (ESLint, pylint)
• Structured JSON output: Machine-readable output for CI pipelines and automated systems
• Human-readable reports: Color-coded terminal output for quick manual debugging
• Stack trace extraction: Automatically finds and surfaces relevant stack traces
• Fix suggestions: Category-aware fix recommendations based on failure patterns
• Handles large repos: Processes logs with 10,000+ lines efficiently via streaming line-by-line parsing

Installation

pip install gh-actions-parser

Or from source:

git clone https://github.com/DeepSeekCode/gh-actions-parser.git
cd gh-actions-parser
pip install -e .

Usage

Basic usage

# Parse a failed run
gh-parse https://github.com/owner/repo/actions/runs/1234567890

# Using an authentication token (recommended to avoid rate limits)
gh-parse https://github.com/owner/repo/actions/runs/1234567890 -t ghp_xxxx

# Using GITHUB_TOKEN environment variable
export GITHUB_TOKEN=ghp_xxxx
gh-parse https://github.com/owner/repo/actions/runs/1234567890

JSON output mode

gh-parse https://github.com/owner/repo/actions/runs/1234567890 --json

Example JSON output:

{
  "run_url": "https://github.com/test/repo/actions/runs/12345",
  "repository": "test/repo",
  "workflow": "CI",
  "conclusion": "failure",
  "failing_steps": [
    {
      "step_name": "Run tests",
      "step_number": 5,
      "error_message": "AssertionError: assert 'Updated' == 'Updated Name'",
      "stack_trace": "File \"tests/test_api.py\", line 42, in test_update_user\n    assert result[\"name\"] == \"Updated Name\"",
      "failure_category": "test_failure"
    }
  ],
  "suggested_fixes": [
    "Check expected vs actual values in the assertion — the test expectation may need updating",
    "Run tests locally with the same environment to reproduce the failure"
  ],
  "error_count": 2
}

Failure Categories

Category	Description	Example Patterns
test_failure	Test runner failures	pytest AssertionError, Jest expect() failures
build_error	Compilation or build failures	TypeScript TS errors, npm ERR!, SyntaxError
lint_error	Linter violations	ESLint errors, pylint E/W violations
unknown	Unclassified failures	Any error that doesn't match known patterns

Supported Patterns

Test Failures

• pytest: FAILED, AssertionError, test session summaries
• Jest: ● test ›, expect().toHaveBeenCalledWith(), suite summaries
• General: FAIL, Test Suites: X failed

Build Errors

• TypeScript: error TS2322:, Cannot find module, type errors
• npm/yarn: npm ERR!, yarn error
• Python: SyntaxError, ModuleNotFoundError, ImportError
• Go: go build.*failed

Lint Errors

• ESLint: error path/to/file:line:col, no-console, no-undef
• pylint: E0602:, W0611:
• black/prettier: would reformat, prettier.*error

Requirements

• Python 3.10+
• GitHub personal access token (optional, but recommended)
  • Without token: 60 requests/hour
  • With token: 5,000 requests/hour

Development

# Install with dev dependencies
pip install -e ".[dev]"

# Run tests
pytest

# Run tests with coverage
pytest --cov=gh_actions_parser

# Lint
pylint src/gh_actions_parser/

# Type check
mypy src/

License

MIT