{"id":29917630,"url":"https://github.com/trieloff/gh-workflow-peek","last_synced_at":"2025-08-02T05:13:49.389Z","repository":{"id":306932819,"uuid":"1027723354","full_name":"trieloff/gh-workflow-peek","owner":"trieloff","description":"GitHub CLI extension to intelligently filter and highlight errors in GitHub Actions workflow logs by severity","archived":false,"fork":false,"pushed_at":"2025-07-28T14:00:50.000Z","size":40,"stargazers_count":0,"open_issues_count":2,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-07-28T15:08:32.979Z","etag":null,"topics":["ci-cd","debugging","developer-tools","gh-extension","github-actions","github-cli"],"latest_commit_sha":null,"homepage":null,"language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/trieloff.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-07-28T12:42:39.000Z","updated_at":"2025-07-28T13:35:32.000Z","dependencies_parsed_at":"2025-07-28T15:09:13.164Z","dependency_job_id":"e30faa50-42a6-410d-ab45-1b839775c30c","html_url":"https://github.com/trieloff/gh-workflow-peek","commit_stats":null,"previous_names":["trieloff/gh-workflow-peek"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/trieloff/gh-workflow-peek","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/trieloff%2Fgh-workflow-peek","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/trieloff%2Fgh-workflow-peek/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/trieloff%2Fgh-workflow-peek/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/trieloff%2Fgh-workflow-peek/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/trieloff","download_url":"https://codeload.github.com/trieloff/gh-workflow-peek/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/trieloff%2Fgh-workflow-peek/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":268338344,"owners_count":24234540,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-08-02T02:00:12.353Z","response_time":74,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ci-cd","debugging","developer-tools","gh-extension","github-actions","github-cli"],"created_at":"2025-08-02T05:13:43.888Z","updated_at":"2025-08-02T05:13:49.368Z","avatar_url":"https://github.com/trieloff.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# gh-workflow-peek\n\nA GitHub CLI extension to intelligently filter and highlight errors in GitHub Actions workflow logs by severity, exhausting higher-priority issues before showing lower ones. Perfect for developers and AI coding agents working with limited context windows.\n\n![a_sleek_modern_di_image](https://github.com/user-attachments/assets/451a28c1-ccb5-4bae-bb16-b94b45f9cebf)\n\n\n## Features\n\n- **Smart Error Prioritization**: Automatically categorizes and prioritizes errors by severity (fatal → error → warn → fail → assert → exception)\n- **Auto-Detection**: When no run ID is specified, automatically detects and analyzes:\n  - Failed PR checks (if in a PR context)\n  - Recent failed workflow runs\n- **Flexible Job Selection**: Select jobs by index, ID, or name pattern\n- **Context Control**: Show configurable lines of context around matches\n- **Custom Pattern Matching**: Search for specific patterns with highest priority\n- **Line Range Filtering**: Focus on specific portions of large logs\n- **Clean Output**: Shows accurate counts of remaining unshown matches by severity\n\n## Installation\n\nInstall the extension using the GitHub CLI:\n\n```bash\ngh extension install trieloff/gh-workflow-peek\n```\n\n## Usage\n\n### Quick Start\n\n```bash\n# Auto-detect and analyze failed PR checks or recent failures\ngh workflow-peek\n\n# Analyze a specific workflow run\ngh workflow-peek 16566617599\n\n# Select a specific job by index\ngh workflow-peek 16566617599 --job 3\n\n# Search for specific patterns\ngh workflow-peek 16566617599 --match 'connection refused' --context 5\n```\n\n### Command Reference\n\n```\ngh workflow-peek [RUN_ID] [OPTIONS]\n\nOPTIONS:\n  [RUN_ID]             GitHub Actions run ID (optional)\n  --id RUN_ID          Alternative way to specify run ID\n  --job, -j JOB        Select job by:\n                       - Index: 3\n                       - ID: 32141145124\n                       - Name: \"Python on Windows\"\n  --context, -c NUM    Lines of context around matches (default: 0)\n  --max, -m NUM        Maximum lines to show (default: 100)\n  --from, -f NUM       Start from line NUM (default: 0 = beginning)\n  --upto, -u NUM       End at line NUM (default: 0 = end)\n  --match, -p PATTERN  Custom pattern to search (highest priority)\n  --repo, -r REPO      Repository (default: current directory's repo)\n  --version, -v        Show version information\n  --help, -h           Show this help message\n```\n\n### Severity Levels\n\nThe extension prioritizes errors in the following order:\n\n1. **Custom match** (--match) - blue\n2. **fatal** - red\n3. **error** - orange\n4. **warn/warning** - yellow\n5. **fail/failed** - yellow\n6. **assert** - magenta\n7. **exception/traceback** - cyan\n\nHigher severity issues are exhausted before showing lower severity ones, ensuring you see the most critical problems first.\n\n## Usage with AI Coding Assistants\n\nThis extension is particularly useful for AI coding assistants that need to efficiently analyze CI failures within limited context windows:\n\n```bash\n# Get a quick overview of the most critical errors\ngh workflow-peek --max 20\n\n# Focus on specific error types\ngh workflow-peek --match 'TypeError|ImportError' --max 50\n\n# Analyze test failures with context\ngh workflow-peek --match 'FAILED|AssertionError' --context 3\n```\n\n### Integration Tips for AI Agents\n\n1. **Start with Auto-Detection**: Let the extension automatically find and analyze the most relevant failed run\n2. **Use Small --max Values**: Start with `--max 20` to get a quick overview without consuming too much context\n3. **Iterate with Specific Patterns**: Once you identify the issue type, use `--match` to focus on specific errors\n4. **Leverage Job Selection**: If multiple jobs failed, analyze them one by one using `--job`\n\n## Examples\n\n### Auto-detect and analyze failures\n```bash\ngh workflow-peek\n```\nThis will:\n- Check for failed PR checks first\n- Fall back to recent failed workflow runs\n- Auto-analyze the top failed run with sensible defaults\n\n### Analyze specific workflow run\n```bash\ngh workflow-peek 16566617599\n```\n\n### Select specific job by index\n```bash\ngh workflow-peek 16566617599 --job 2\n```\n\n### Select job by name pattern\n```bash\ngh workflow-peek 16566617599 --job \"Python 3.11\"\n```\n\n### Search for database errors with context\n```bash\ngh workflow-peek 16566617599 --match 'connection|database|timeout' --context 5\n```\n\n### Focus on test failures in a specific line range\n```bash\ngh workflow-peek 16566617599 --from 1000 --upto 2000 --match 'FAILED|ERROR' --max 30\n```\n\n### Combine multiple filters for precise analysis\n```bash\ngh workflow-peek 16566617599 --job \"backend-tests\" --match 'AssertionError' --context 3 --max 25\n```\n\n## Requirements\n\n- GitHub CLI (`gh`) - authenticated with `gh auth login`\n- `jq` - for JSON parsing\n- `column` - for formatting output (usually part of util-linux)\n- `awk` - for text processing (standard on most systems)\n- Bash 4.0 or higher\n\n## Troubleshooting\n\n### Authentication Issues\nIf you see \"Error: GitHub CLI is not authenticated\", run:\n```bash\ngh auth login\n```\n\n### Missing Dependencies\nThe extension will check for required dependencies and provide installation instructions if any are missing.\n\n### No Failed Jobs Found\nIf the extension reports \"No failed jobs found\", the workflow run might:\n- Still be in progress\n- Have been cancelled rather than failed\n- Have all jobs succeeded\n\n### Repository Detection\nIf running outside a git repository, specify the repository explicitly:\n```bash\ngh workflow-peek 16566617599 --repo owner/repo\n```\n\n## Contributing\n\nContributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.\n\n### Development\n\n1. Clone the repository\n2. Make your changes\n3. Run `shellcheck gh-workflow-peek` to check for issues\n4. Test your changes with various workflow scenarios\n5. Submit a pull request\n\n## License\n\n[Apache-2.0](LICENSE)\n\n## Related Vibe Coding Projects\n\nThis tool is part of a collection of vibe coding projects designed to enhance AI-assisted development:\n\n- **[ai-aligned-git](https://github.com/trieloff/ai-aligned-git)** - A humorous git wrapper that enforces best practices for AI coding agents, preventing problematic git behaviors like indiscriminate file additions\n- **[vibe-coded-badge-action](https://github.com/trieloff/vibe-coded-badge-action)** - A GitHub Action that analyzes your repository's git history to determine what percentage of commits were made by AI tools and displays it as a badge\n- **[gh-workflow-peek](https://github.com/trieloff/gh-workflow-peek)** - This project - intelligently filters and highlights errors in GitHub Actions workflow logs for efficient debugging\n\n## Acknowledgments\n\nThis extension was designed with AI coding assistants in mind, recognizing the need for efficient log analysis within limited context windows. Special thanks to the GitHub CLI team for making extensions possible.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftrieloff%2Fgh-workflow-peek","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftrieloff%2Fgh-workflow-peek","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftrieloff%2Fgh-workflow-peek/lists"}