Skip to content

Commit b617dbd

Browse files
openhands-agentopenhands-agent
committed
Add debug-github-ci and debug-jenkins-ci skills
Squashed commit from add-ci-debug-skills branch with conflict resolution. Includes all changes from the original PR with main branch merged. Co-authored-by: openhands <openhands@all-hands.dev>
1 parent 3d32686 commit b617dbd

15 files changed

Lines changed: 2435 additions & 0 deletions

File tree

‎marketplaces/default.json‎

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -401,6 +401,32 @@
401401
"hosting"
402402
]
403403
},
404+
{
405+
"name": "debug-github-ci",
406+
"source": "./debug-github-ci",
407+
"description": "Debug GitHub Actions CI failures by fetching logs, identifying root causes, and suggesting fixes.",
408+
"category": "debugging",
409+
"keywords": [
410+
"github",
411+
"ci",
412+
"actions",
413+
"debugging",
414+
"workflow"
415+
]
416+
},
417+
{
418+
"name": "debug-jenkins-ci",
419+
"source": "./debug-jenkins-ci",
420+
"description": "Debug Jenkins CI/CD pipeline failures by fetching logs, identifying root causes, and suggesting fixes.",
421+
"category": "debugging",
422+
"keywords": [
423+
"jenkins",
424+
"ci",
425+
"pipeline",
426+
"debugging",
427+
"build"
428+
]
429+
},
404430
{
405431
"name": "linear",
406432
"source": "./linear",

‎plugins/debug-github-ci/README.md‎

Lines changed: 161 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,161 @@
1+
# Debug GitHub CI
2+
3+
Automated debugging of GitHub Actions CI failures using OpenHands agents.
4+
5+
## Overview
6+
7+
This extension provides **dual-mode functionality**:
8+
9+
1. **Skill Mode**: A knowledge skill (`SKILL.md`) that provides guidance and context for debugging CI failures interactively via OpenHands conversations.
10+
11+
2. **Plugin Mode**: An executable GitHub Action (`action.yml`) that can be triggered automatically when CI fails, running an autonomous debug agent.
12+
13+
Use **skill mode** when working interactively with OpenHands to debug CI issues. Use **plugin mode** to automate CI failure analysis in your GitHub workflows.
14+
15+
## Quick Start
16+
17+
Copy the workflow file to your repository:
18+
19+
```bash
20+
mkdir -p .github/workflows
21+
curl -o .github/workflows/debug-ci-failure.yml \
22+
https://raw.githubusercontent.com/OpenHands/extensions/main/plugins/debug-github-ci/workflows/debug-ci-failure.yml
23+
```
24+
25+
Then configure the required secrets (see [Installation](#installation) below).
26+
27+
## Features
28+
29+
- **Automatic CI Failure Analysis**: Triggered when workflow runs fail
30+
- **Log Analysis**: Fetches and analyzes failed job logs to identify root causes
31+
- **Actionable Suggestions**: Posts comments with specific fixes and commands
32+
- **Error Pattern Recognition**: Identifies common CI failure patterns
33+
- **Context-Aware**: Considers recent commits and PR changes
34+
35+
## Plugin Contents
36+
37+
```
38+
plugins/debug-github-ci/
39+
├── README.md # This file
40+
├── action.yml # Composite GitHub Action
41+
├── skills/ # Symbolic links to debug skills
42+
│ └── debug-github-ci -> ../../../skills/debug-github-ci
43+
├── workflows/ # Example GitHub workflow files
44+
│ └── debug-ci-failure.yml
45+
└── scripts/ # Python scripts for debug execution
46+
├── agent_script.py # Main CI debug agent script
47+
└── prompt.py # Prompt template for debugging
48+
```
49+
50+
## Installation
51+
52+
### 1. Copy the Workflow File
53+
54+
Copy the workflow file to your repository's `.github/workflows/` directory:
55+
56+
```bash
57+
mkdir -p .github/workflows
58+
curl -o .github/workflows/debug-ci-failure.yml \
59+
https://raw.githubusercontent.com/OpenHands/extensions/main/plugins/debug-github-ci/workflows/debug-ci-failure.yml
60+
```
61+
62+
### 2. Configure Secrets
63+
64+
Add the following secrets in your repository settings (**Settings → Secrets and variables → Actions**):
65+
66+
| Secret | Required | Description |
67+
|--------|----------|-------------|
68+
| `LLM_API_KEY` | Yes | API key for your LLM provider |
69+
| `GITHUB_TOKEN` | Auto | Provided automatically by GitHub Actions |
70+
71+
### 3. Customize the Workflow (Optional)
72+
73+
Edit the workflow file to customize:
74+
75+
```yaml
76+
- name: Debug CI Failure
77+
uses: OpenHands/extensions/plugins/debug-github-ci@main
78+
with:
79+
# LLM model to use
80+
llm-model: anthropic/claude-sonnet-4-5-20250929
81+
82+
# Secrets
83+
llm-api-key: ${{ secrets.LLM_API_KEY }}
84+
github-token: ${{ secrets.GITHUB_TOKEN }}
85+
```
86+
87+
## Usage
88+
89+
### Automatic Triggers
90+
91+
CI debugging is automatically triggered when:
92+
93+
1. A workflow run fails on the repository
94+
2. The `debug-ci` label is added to a PR with failed checks
95+
96+
### Manual Trigger
97+
98+
You can manually trigger debugging:
99+
100+
1. Go to **Actions** tab
101+
2. Select **Debug CI Failure** workflow
102+
3. Click **Run workflow**
103+
4. Enter the failed run ID
104+
105+
## Action Inputs
106+
107+
| Input | Required | Default | Description |
108+
|-------|----------|---------|-------------|
109+
| `llm-model` | No | `anthropic/claude-sonnet-4-5-20250929` | LLM model to use |
110+
| `llm-base-url` | No | `''` | Custom LLM endpoint URL |
111+
| `run-id` | No | Auto | Specific workflow run ID to debug |
112+
| `extensions-repo` | No | `OpenHands/extensions` | Extensions repository |
113+
| `extensions-version` | No | `main` | Git ref (tag, branch, or SHA) |
114+
| `llm-api-key` | Yes | - | LLM API key |
115+
| `github-token` | Yes | - | GitHub token for API access |
116+
117+
## What Gets Analyzed
118+
119+
The agent analyzes:
120+
121+
1. **Failed job logs**: Console output from failed steps
122+
2. **Error messages**: Specific error patterns and stack traces
123+
3. **Recent commits**: Changes that may have caused the failure
124+
4. **Workflow configuration**: Issues in the workflow YAML
125+
5. **Dependencies**: Version conflicts or missing packages
126+
127+
## Output
128+
129+
The agent posts a comment with:
130+
131+
- **Root Cause Analysis**: What caused the failure
132+
- **Suggested Fixes**: Specific commands or code changes
133+
- **Prevention Tips**: How to avoid similar failures
134+
135+
## Troubleshooting
136+
137+
### Debug Not Triggered
138+
139+
1. Ensure the workflow file is in `.github/workflows/`
140+
2. Verify secrets are configured correctly
141+
3. Check that the workflow has `workflow_run` trigger permissions
142+
143+
### Analysis Incomplete
144+
145+
1. Check if logs are available (some expire after 90 days)
146+
2. Verify the `GITHUB_TOKEN` has read access to workflow logs
147+
3. Increase timeout if analysis takes too long
148+
149+
## Security
150+
151+
- Uses `workflow_run` event for secure access to secrets
152+
- Only analyzes public workflow logs
153+
- Does not execute any code from the failed run
154+
155+
## Contributing
156+
157+
See the main [extensions repository](https://github.com/OpenHands/extensions) for contribution guidelines.
158+
159+
## License
160+
161+
This plugin is part of the OpenHands extensions repository. See [LICENSE](../../LICENSE) for details.

‎plugins/debug-github-ci/action.yml‎

Lines changed: 135 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,135 @@
1+
---
2+
name: OpenHands Debug GitHub CI
3+
description: Automated CI failure debugging using OpenHands agent
4+
author: OpenHands
5+
6+
branding:
7+
icon: alert-circle
8+
color: red
9+
10+
inputs:
11+
llm-model:
12+
description: LLM model to use for debugging
13+
required: false
14+
default: anthropic/claude-sonnet-4-5-20250929
15+
llm-base-url:
16+
description: LLM base URL (optional, for custom LLM endpoints)
17+
required: false
18+
default: ''
19+
run-id:
20+
description: Specific workflow run ID to debug (auto-detected if not provided)
21+
required: false
22+
default: ''
23+
extensions-repo:
24+
description: GitHub repository for extensions (owner/repo)
25+
required: false
26+
default: OpenHands/extensions
27+
extensions-version:
28+
description: Git ref to use for extensions (tag, branch, or commit SHA)
29+
required: false
30+
default: main
31+
llm-api-key:
32+
description: LLM API key (required)
33+
required: true
34+
github-token:
35+
description: GitHub token for API access (required)
36+
required: true
37+
use-cache:
38+
description: |
39+
Enable uv cache for faster dependency installation (default: false).
40+
Disabled by default since debug tools benefit from fresh state to
41+
avoid masking environment-related issues.
42+
required: false
43+
default: 'false'
44+
45+
runs:
46+
using: composite
47+
steps:
48+
- name: Checkout extensions repository
49+
uses: actions/checkout@v4
50+
with:
51+
repository: ${{ inputs.extensions-repo }}
52+
ref: ${{ inputs.extensions-version }}
53+
path: extensions
54+
55+
- name: Set up Python
56+
uses: actions/setup-python@v5
57+
with:
58+
python-version: '3.12'
59+
60+
- name: Install uv
61+
uses: astral-sh/setup-uv@v6
62+
with:
63+
enable-cache: ${{ inputs.use-cache == 'true' }}
64+
65+
- name: Install GitHub CLI
66+
shell: bash
67+
run: |
68+
sudo apt-get update
69+
sudo apt-get install -y gh
70+
71+
- name: Determine run ID
72+
id: get-run-id
73+
shell: bash
74+
env:
75+
GITHUB_TOKEN: ${{ inputs.github-token }}
76+
INPUT_RUN_ID: ${{ inputs.run-id }}
77+
run: |
78+
if [ -n "$INPUT_RUN_ID" ]; then
79+
echo "run_id=$INPUT_RUN_ID" >> $GITHUB_OUTPUT
80+
elif [ -n "${{ github.event.workflow_run.id }}" ]; then
81+
echo "run_id=${{ github.event.workflow_run.id }}" >> $GITHUB_OUTPUT
82+
else
83+
# Get the most recent failed run
84+
RUN_ID=$(gh run list --status failure --limit 1 --json databaseId --jq '.[0].databaseId' 2>/dev/null || echo "")
85+
if [ -z "$RUN_ID" ]; then
86+
echo "::error::No run ID provided and no failed runs found"
87+
exit 1
88+
fi
89+
echo "run_id=$RUN_ID" >> $GITHUB_OUTPUT
90+
fi
91+
92+
- name: Check required configuration
93+
shell: bash
94+
env:
95+
LLM_API_KEY: ${{ inputs.llm-api-key }}
96+
GITHUB_TOKEN: ${{ inputs.github-token }}
97+
run: |
98+
if [ -z "$LLM_API_KEY" ]; then
99+
echo "Error: llm-api-key is required."
100+
exit 1
101+
fi
102+
103+
if [ -z "$GITHUB_TOKEN" ]; then
104+
echo "Error: github-token is required."
105+
exit 1
106+
fi
107+
108+
echo "Run ID to debug: ${{ steps.get-run-id.outputs.run_id }}"
109+
echo "Repository: ${{ github.repository }}"
110+
echo "LLM model: ${{ inputs.llm-model }}"
111+
112+
- name: Run CI debug analysis
113+
shell: bash
114+
env:
115+
LLM_MODEL: ${{ inputs.llm-model }}
116+
LLM_BASE_URL: ${{ inputs.llm-base-url }}
117+
LLM_API_KEY: ${{ inputs.llm-api-key }}
118+
GITHUB_TOKEN: ${{ inputs.github-token }}
119+
RUN_ID: ${{ steps.get-run-id.outputs.run_id }}
120+
REPO_NAME: ${{ github.repository }}
121+
# Marker to prevent recursive debugging - checked by agent_script.py
122+
OH_DEBUG_WORKFLOW: 'true'
123+
run: |
124+
uv run --with openhands-sdk --with openhands-tools \
125+
python extensions/plugins/debug-github-ci/scripts/agent_script.py
126+
127+
- name: Upload logs as artifact
128+
uses: actions/upload-artifact@v4
129+
if: always()
130+
with:
131+
name: openhands-ci-debug-logs
132+
path: |
133+
*.log
134+
output/
135+
retention-days: 7

0 commit comments

Comments
 (0)