Skip to content

Commit 5d18118

Browse files
CopilotCopilot
authored
feat: import 👾 Issue Monster workflow (#366)
1 parent cbf4f2d commit 5d18118

3 files changed

Lines changed: 795 additions & 0 deletions

File tree

‎README.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -98,6 +98,7 @@ You can use the "/plan" agent to turn the reports into actionable issues which c
9898

9999
### Issue Farming Workflows
100100

101+
- [👾 Issue Monster](docs/issue-monster.md) - Automatically assign issues labeled `cookie` to the Copilot coding agent every 30 minutes
101102
- [🔒 Sub-Issue Closer](docs/sub-issue-closer.md) - Automatically close parent issues when all their sub-issues are complete
102103
- [🌳 Issue Arborist](docs/issue-arborist.md) - Automatically organize issues by linking related issues as parent-child sub-issues
103104

‎docs/issue-monster.md‎

Lines changed: 126 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,126 @@
1+
# 👾 Issue Monster
2+
3+
> For an overview of all available workflows, see the [main README](../README.md).
4+
5+
**Automated workflow that assigns approved issues to the Copilot coding agent every 30 minutes**
6+
7+
The [Issue Monster workflow](../workflows/issue-monster.md?plain=1) is the Cookie Monster of issues 🍪 — it runs every 30 minutes, scans the issue tracker for open issues labeled `cookie`, scores and prioritizes them, and assigns up to three per run to the Copilot coding agent for automated resolution.
8+
9+
## Installation
10+
11+
```bash
12+
# Install the 'gh aw' extension
13+
gh extension install github/gh-aw
14+
15+
# Add the workflow to your repository
16+
gh aw add-wizard githubnext/agentics/issue-monster
17+
```
18+
19+
This walks you through adding the workflow to your repository.
20+
21+
## How It Works
22+
23+
```mermaid
24+
graph LR
25+
A[Every 30 minutes] --> B[Check rate limiting]
26+
B -->|Rate limited| C[Skip — wait for next run]
27+
B -->|OK| D[Search issues with 'cookie' label]
28+
D --> E[Filter & score candidates]
29+
E --> F[Select up to 3 independent issues]
30+
F --> G[Assign each to Copilot]
31+
G --> H[Comment on assigned issues]
32+
F -->|No suitable issues| I[Noop — explain why]
33+
```
34+
35+
### Pre-Activation Job
36+
37+
Before the agent runs, a GitHub Actions job searches for candidate issues, applies all filtering, scores them by priority, and passes the results to the agent. This means the agent gets a clean, pre-ranked list without needing to make extra API calls.
38+
39+
### Smart Filtering
40+
41+
The workflow skips issues that are:
42+
43+
| Condition | Reason |
44+
|-----------|--------|
45+
| Already assigned | Avoid duplicate work |
46+
| Have open Copilot PRs | Already being worked on |
47+
| Have closed/merged PRs | Treating as complete |
48+
| Are parent issues with sub-issues | Organizing issues, not tasks |
49+
| Carry exclusion labels | `wontfix`, `duplicate`, `blocked`, `no-bot`, etc. |
50+
| Have `campaign:*` labels | Managed by campaign orchestrators |
51+
52+
### Priority Scoring
53+
54+
Issues are scored and ranked before the agent sees them:
55+
56+
| Label | Points |
57+
|-------|--------|
58+
| `community` | +60 *(external contributors always first)* |
59+
| `good first issue` | +50 |
60+
| `security` | +45 |
61+
| `bug` | +40 |
62+
| `documentation` | +35 |
63+
| `enhancement` / `feature` | +30 |
64+
| `performance` | +25 |
65+
| `tech-debt` / `refactoring` | +20 |
66+
| Has any priority label | +10 |
67+
| Age bonus (older issues) | +0–20 |
68+
69+
### Topic Separation
70+
71+
The three selected issues must be completely independent in scope — different areas of the codebase, different components, no overlapping file changes. This prevents conflicting pull requests.
72+
73+
### Sibling Awareness
74+
75+
For sub-issues of a common parent (with `task` or `plan` labels), the workflow processes them one at a time, oldest first. If one sibling already has an open Copilot PR, all other siblings are skipped until it's merged or closed.
76+
77+
### Rate-Limit Protection
78+
79+
Before each run, the workflow checks recent Copilot PRs for comments indicating API rate limiting. If rate limiting is detected, the run is skipped entirely to avoid making things worse.
80+
81+
## The `cookie` Label
82+
83+
Issue Monster only processes issues labeled `cookie`. This label acts as a work-queue gate — it signals that an issue has been reviewed and approved for automated resolution. Add this label manually or automate it with another workflow (for example, your triage workflow can add `cookie` to issues that are suitable for the Copilot coding agent).
84+
85+
## Configuration
86+
87+
After installing, you can customize the workflow by editing `workflows/issue-monster.md`:
88+
89+
- **Exclusion labels**: Edit the `excludeLabels` array in the pre-activation script
90+
- **Priority scores**: Adjust the scoring values in the `.map(issue => ...)` section
91+
- **Issues per run**: Change `max: 3` in the `assign-to-agent` safe-output
92+
- **Schedule**: Modify `schedule: every 30m` (e.g., `every 1h`, `daily`)
93+
94+
After editing, run `gh aw compile` to apply your changes.
95+
96+
## Permissions Required
97+
98+
- `contents: read` — Read repository contents
99+
- `issues: read` — Search and read issues
100+
- `pull-requests: read` — Check for existing Copilot PRs
101+
- `copilot-requests: write` — Assign issues to the Copilot coding agent
102+
103+
## Example Run
104+
105+
A typical run looks like this:
106+
107+
1. Pre-activation job finds 12 open `cookie` issues
108+
2. Rate-limit check passes (no recent rate-limited PRs)
109+
3. After filtering: 5 candidate issues remain
110+
4. Agent selects 3 that are independent in topic
111+
5. Agent assigns each to Copilot and posts a comment:
112+
113+
> 🍪 **Issue Monster selected this for Copilot**
114+
>
115+
> I've identified this issue as a good candidate for automated resolution and requested assignment to the Copilot coding agent.
116+
>
117+
> If assignment succeeds, the Copilot coding agent will analyze the issue and create a pull request with the fix.
118+
>
119+
> Om nom nom! 🍪
120+
121+
## Learn More
122+
123+
- [Issue Monster source workflow](https://github.com/github/gh-aw/blob/main/.github/workflows/issue-monster.md)
124+
- [Sub-Issue Closer](sub-issue-closer.md) — automatically closes parent issues when all sub-issues are complete
125+
- [Issue Arborist](issue-arborist.md) — automatically organize issues by linking related issues as parent-child sub-issues
126+
- [Issue Triage](issue-triage.md) — label and prioritize new issues (can add the `cookie` label to suitable issues)

0 commit comments

Comments
 (0)