Skip to content

Commit 0a50443

Browse files
wilkerHopwilkerHop
committed
docs: add auto-issue workflow documentation
- Update README with automated issue creation section - Add detailed auto-issue documentation to SCRIPTS.md - Create AUTO_ISSUE.md with workflow guide - Document duplicate prevention mechanism - Include customization and troubleshooting guides
1 parent c677866 commit 0a50443

3 files changed

Lines changed: 169 additions & 0 deletions

File tree

‎rust_blender_anim/AUTO_ISSUE.md‎

Lines changed: 138 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,138 @@
1+
# Auto-Issue on Failure Workflow
2+
3+
## Overview
4+
5+
This workflow automatically creates GitHub issues when the CI Pipeline fails, making it easy to track and fix problems.
6+
7+
## How It Works
8+
9+
### Trigger
10+
```yaml
11+
on:
12+
workflow_run:
13+
workflows: ["CI Pipeline"]
14+
types: [completed]
15+
```
16+
17+
The workflow triggers when the "CI Pipeline" workflow completes. It only runs if the conclusion is 'failure'.
18+
19+
### Process
20+
21+
1. **Failure Detection**
22+
- Checks if `workflow_run.conclusion == 'failure'`
23+
- Extracts failure metadata (workflow name, run number, branch, commit, actor)
24+
25+
2. **Duplicate Prevention**
26+
- Searches for existing open issues with the `ci-failure` label
27+
- Checks if an issue already exists for the same workflow and branch
28+
- If found, adds a comment instead of creating a new issue
29+
30+
3. **Issue Creation**
31+
- **Title Format**: `🔴 CI Failure: [Workflow Name] #[Run Number] on [Branch]`
32+
- **Labels**: `ci-failure`, `bug`, `automated`
33+
- **Body Includes**:
34+
- Failure details table
35+
- Direct link to failed run
36+
- Investigation steps
37+
- Common failure points checklist
38+
- Reproduction instructions
39+
- Action items checklist
40+
41+
## Example Issue
42+
43+
### Title
44+
```
45+
🔴 CI Failure: CI Pipeline #42 on main
46+
```
47+
48+
### Content Includes
49+
50+
- **Details Table**: Workflow name, run number, branch, commit SHA, actor
51+
- **Investigation Steps**:
52+
- Review logs
53+
- Check recent changes
54+
- Reproduce locally
55+
- Common failure points
56+
57+
- **Next Steps Checklist**:
58+
- [ ] Identify root cause
59+
- [ ] Fix the issue
60+
- [ ] Run health checks locally
61+
- [ ] Push fix and verify CI passes
62+
- [ ] Close this issue
63+
64+
## Benefits
65+
66+
✅ **Automatic Tracking**: No manual issue creation needed
67+
✅ **No Duplicates**: Smart detection of existing issues
68+
✅ **Rich Context**: All relevant information in one place
69+
✅ **Actionable**: Clear steps to investigate and resolve
70+
✅ **Linked**: Direct links to failed runs and commits
71+
72+
## Permissions Required
73+
74+
The workflow requires:
75+
- `issues: write` - To create and comment on issues
76+
- `actions: read` - To read workflow run information
77+
- `contents: read` - To checkout code
78+
79+
## Labels Used
80+
81+
- **ci-failure**: Identifies CI-related issues
82+
- **bug**: Marks it as a bug
83+
- **automated**: Indicates auto-generated content
84+
85+
## Customization
86+
87+
### Change Workflow Trigger
88+
Edit line 4 to monitor different workflows:
89+
```yaml
90+
workflows: ["Your Workflow Name"]
91+
```
92+
93+
### Modify Issue Content
94+
Edit the `issue_body.md` section in the "Extract failure information" step.
95+
96+
### Add More Labels
97+
Edit the labels array in the "Create or update issue" step:
98+
```javascript
99+
labels: ['ci-failure', 'bug', 'automated', 'your-label']
100+
```
101+
102+
## Testing
103+
104+
To test this workflow:
105+
106+
1. Push code that will cause CI to fail
107+
2. Wait for CI Pipeline to complete with failure
108+
3. Check the Issues tab for a new issue
109+
4. Push another failure to the same branch
110+
5. Verify a comment is added instead of creating a new issue
111+
112+
## Workflow Dependencies
113+
114+
This workflow depends on:
115+
- **CI Pipeline** workflow being named exactly "CI Pipeline"
116+
- GitHub Actions being enabled
117+
- Issue creation permissions in the repository
118+
119+
## Troubleshooting
120+
121+
### Issue Not Created
122+
123+
**Check**:
124+
- Workflow run conclusion is "failure" (not "cancelled" or "skipped")
125+
- Repository has issues enabled
126+
- Workflow has proper permissions
127+
128+
### Duplicate Issues Created
129+
130+
**Check**:
131+
- Label `ci-failure` is applied correctly
132+
- Issue title matching logic in `check_existing` step
133+
134+
### Missing Information
135+
136+
**Check**:
137+
- Workflow run event data is available
138+
- All environment variables are properly set

‎rust_blender_anim/README.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -78,6 +78,11 @@ This project includes a GitHub Actions workflow that:
7878
- `rendered-video` - The final MP4 animation (30 day retention)
7979
- `generated-script` - The Python script for Blender (7 day retention)
8080

81+
**Automated Issue Creation**:
82+
- If the CI fails, a GitHub issue is automatically created
83+
- Issues include failure details, investigation steps, and direct links to logs
84+
- Prevents duplicate issues for the same workflow and branch
85+
8186
To enable the CI pipeline, push the code to GitHub and the workflow will run automatically on push/PR to main/master branches.
8287

8388
## What Happens

‎rust_blender_anim/SCRIPTS.md‎

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -79,6 +79,32 @@ The workflow runs automatically on:
7979
3. Scroll to the "Artifacts" section at the bottom
8080
4. Download `rendered-video` to get the MP4 file
8181

82+
### Auto-Issue on Failure Workflow
83+
84+
This project includes an automated issue creation system (`.github/workflows/auto-issue-on-failure.yml`) that:
85+
86+
**Triggers when**: The CI Pipeline workflow fails
87+
88+
**Actions taken**:
89+
1. Extracts failure information (workflow name, run number, branch, commit)
90+
2. Checks for existing open issues with the same workflow and branch
91+
3. Either:
92+
- Creates a new issue with the `ci-failure`, `bug`, and `automated` labels
93+
- Or adds a comment to an existing issue if one already exists
94+
95+
**Issue includes**:
96+
- 🚨 Descriptive title: `🔴 CI Failure: [Workflow] #[Run] on [Branch]`
97+
- 📊 Details table with workflow info, run number, commit SHA, and actor
98+
- 🔗 Direct link to the failed workflow run
99+
- 🔍 Investigation steps and common failure points
100+
- 📋 Checklist for fixing and closing the issue
101+
102+
**Benefits**:
103+
- ✅ Automatic tracking of CI failures
104+
- ✅ No duplicate issues for the same workflow/branch
105+
- ✅ Clear, actionable investigation steps
106+
- ✅ Links to relevant runs and commits
107+
82108
### Local Simulation
83109

84110
To simulate the CI pipeline locally:

0 commit comments

Comments
 (0)