GitHub Actions Log Parser

gha-log-parser is a small Python CLI that turns a GitHub Actions run URL into a structured JSON failure summary. It identifies the failing job and step, extracts the most useful error line and stack trace, and classifies the failure as a test, build, lint, or unknown failure.

Install

python -m pip install -e .

For public repositories, the GitHub API often works without a token. For private repositories or higher rate limits, set GITHUB_TOKEN.

export GITHUB_TOKEN=ghp_your_token_here

On Windows PowerShell:

$env:GITHUB_TOKEN = "ghp_your_token_here"

Usage

Parse a public GitHub Actions run:

gha-log-parser https://github.com/owner/repo/actions/runs/123456789

Pretty-print the JSON:

gha-log-parser https://github.com/owner/repo/actions/runs/123456789 --pretty

Parse a local log file while developing or testing:

gha-log-parser https://github.com/owner/repo/actions/runs/123456789 --logs-file failed-job.log --step "Run tests" --pretty

Example Output

{
  "run_url": "https://github.com/acme/widget/actions/runs/123456789",
  "repository": "acme/widget",
  "run_id": "123456789",
  "status": "failed",
  "failures": [
    {
      "job_name": "test",
      "failing_step_name": "Run pytest",
      "error_message": "FAILED tests/test_api.py::test_create_user - AssertionError: expected 201 got 500",
      "stack_trace": [
        "tests/test_api.py:42: AssertionError"
      ],
      "suggested_fix_category": "test_failure",
      "log_excerpt": [
        "FAILED tests/test_api.py::test_create_user - AssertionError: expected 201 got 500",
        "tests/test_api.py:42: AssertionError"
      ]
    }
  ]
}

Failure Types

The parser recognizes these categories:

• test_failure: pytest, unittest, Jest, Vitest, or assertion-style failures.
• build_error: TypeScript, compiler, bundler, syntax, or module resolution failures.
• lint_error: ESLint, Pylint, Ruff, Flake8, Biome, Prettier, or formatting failures.
• unknown: the log contains an error, but it does not match a known pattern.

Development

Run the test suite:

python -m unittest discover -s tests

Run Pylint:

python -m pylint src tests

The public functions include type hints and the tests use mocked GitHub API responses, so the suite does not need network access.