|
1 | 1 | # GitHub issue triage |
2 | 2 |
|
3 | | -Prioritize open issues and establish acceptance criteria before marking them ready for development. |
4 | | - |
5 | | -Schedule this automation independently and select its agent profile. The profile |
6 | | -chooses the model, tools, and GitHub credential; the PAT needs Issues write access |
7 | | -only. Explicit issue dependencies must be completed before development starts. |
8 | | -The agent checks repository guidance and adjacent code, preserves the author's |
9 | | -issue description, and maintains accepted criteria in one clearly marked section |
10 | | -at the end of the issue body. This lets repository readiness checks evaluate the |
11 | | -same source that developers and reviewers use. When a material design decision |
12 | | -remains unclear after repository research, the agent leaves the body unchanged, |
13 | | -asks focused follow-up questions in a marked comment, and withholds the readiness |
14 | | -label. |
15 | | - |
16 | | -See [SKILL.md](SKILL.md) for configuration and the catalog bundle for its files. |
| 3 | +Prioritize issues and define observable acceptance criteria using |
| 4 | +[SKILL.md](SKILL.md). The scanner honors dependencies and sends changed issues |
| 5 | +to conversations using the selected profile. |
| 6 | + |
| 7 | +## Publication modes |
| 8 | + |
| 9 | +Legacy agent publication is the default. The optional `triage_publication.py` |
| 10 | +helper validates JSON recommendations and checks human inputs before every write. |
| 11 | +It preserves text outside managed markers and edits/deletes only triage-marked |
| 12 | +comments from the authenticated account. It skips identical writes and stops on |
| 13 | +ambiguous markers. GitHub Actions readiness comments provide context, but neither |
| 14 | +change the human-input fingerprint nor override policy. |
| 15 | + |
| 16 | +This opt-in is **not credential isolation**: the agent can still write directly. |
| 17 | +Enforced isolation needs a separate trusted publisher, read-only agent credentials, |
| 18 | +and runtime support for passing results to the publisher. |
| 19 | + |
| 20 | +## Operator setup |
| 21 | + |
| 22 | +Bundle `worker.py`, `triage_publication.py`, `github_client.py`, and |
| 23 | +`agent_conversation.py`. Entrypoint: `python3 worker.py`. |
| 24 | + |
| 25 | +1. Place the publisher, `github_client.py`, and protected config in the delegated |
| 26 | + workspace. Set `triage_publisher_path` and `triage_publisher_config_path` to |
| 27 | + absolute file paths. Set both or neither; neither keeps legacy mode. |
| 28 | +2. Set `triage_publisher_workspace: "shared-host"` only after checking manually |
| 29 | + that the agent can access those paths. The flag asserts access; it does not |
| 30 | + prove sandbox visibility. The scanner checks files and the repository allowlist before dispatch, then |
| 31 | + loads readiness policies from that same protected publisher config for its |
| 32 | + input fingerprints. Do not duplicate policies in the scanner config. Remote/container paths are unsupported. If the |
| 33 | + agent cannot invoke the helper, stop; do not fall back to direct writes. |
| 34 | +3. Cloud conversations are unsupported: bundling does not provision their files, |
| 35 | + and the dispatcher cannot retrieve structured results from them. |
| 36 | + |
| 37 | +Publisher config uses existing `repos` and optional `triage_readiness_policies`: |
| 38 | + |
| 39 | +```json |
| 40 | +{ |
| 41 | + "repos": ["owner/repo"], |
| 42 | + "triage_readiness_policies": { |
| 43 | + "owner/repo": { |
| 44 | + "mode": "authorized-writers", |
| 45 | + "files": {".github/workflows/issue-readiness-check.yml": "<audited GitHub blob SHA>"} |
| 46 | + } |
| 47 | + } |
| 48 | +} |
| 49 | +``` |
| 50 | + |
| 51 | +Audit current policy and pin every relevant file to its actual 40-character |
| 52 | +GitHub blob SHA (the file-content identifier). Only writer-only policies are |
| 53 | +supported: the helper checks current SHAs and live `write`/`maintain`/`admin` |
| 54 | +permission. Never select this mode for a policy that checks issue content. |
| 55 | +Unknown, changed, or unsupported policies block new readiness grants, preserve |
| 56 | +existing labels, and still allow criteria publication. No repository checker runs. |
| 57 | + |
| 58 | +Precreate `ready-for-dev` and `priority:low/medium/high` labels. Use the same |
| 59 | +GitHub account for scanner and publisher. Its fine-grained PAT needs selected-repo |
| 60 | +Issues read/write, Contents read, and permission lookup access. Never put token |
| 61 | +values in prompts or automation definitions. |
| 62 | + |
| 63 | +## Races and retries |
| 64 | + |
| 65 | +- Checks and writes are not atomic: people or other automations can change inputs |
| 66 | + between GET and PATCH. There is no shared lock or all-or-nothing update across |
| 67 | + issue bodies, comments, and labels. Changed inputs stop publication; the next |
| 68 | + scan recomputes the recommendation. |
| 69 | +- The input fingerprint includes human readiness-label changes from the issue |
| 70 | + timeline, but excludes the publisher's and GitHub Actions' label changes. |
| 71 | +- A completion receipt is saved only after publication finishes. Partial writes |
| 72 | + change the guarded-mode delivery key, allowing retries. If an unchanged failure |
| 73 | + is marked finished by the dispatcher, manually retry the same command. |
| 74 | +- Configured policy changes affect the fingerprint. Upstream policy changes alone |
| 75 | + do not automatically retriage unchanged issues with managed markers. |
0 commit comments