GitHub Issue Resolver Runbook

Owner: platform-runners Template: GitHub Issue Resolver (certified, gallery-visible) Expected duration: ~30 minutes Expected cost range: $2–$8 Tool profile: web_automation

This page is referenced from template_seed.py:235 (support_runbook_url) and embedded in the SS-061 support bundle for runs of this template.

Known failure reasons

The template advertises five canonical failure reasons in its known_failure_reasons array. The dashboard’s failure-reason chip maps to one of:

Reason	What happened	First action
`github_token_missing_or_revoked`	The org’s `github_token` credential is missing or no longer accepted.	Check Integrations → GitHub in the dashboard; reconnect if status is “Disconnected”.
`repo_not_accessible_to_app`	The token is valid but cannot see the target repo.	Ask the customer to install the Curate-Me GitHub App on the repo OR grant read+PR-write to the user token.
`tests_did_not_run_to_completion`	The runner started the test step but it timed out or the harness exited non-zero.	Inspect the timeline tail of the run for the last test command and its stderr. Usually a missing CI dep.
`merge_conflict_blocked_pr_open`	The branch was created and committed, but `gh pr create` rejected the open due to a merge conflict.	Customer’s main branch has moved; recommend a rebase + relaunch.
`branch_protection_blocked_push`	The repo’s branch protection rules rejected the agent’s push (e.g. requires signed commits).	Either configure the agent’s signing key for that org or relax the rule for `cm-bot/*` branches.

If the dashboard shows none of the above, the failure happened during container boot and the generic BYOVM runbook applies.

Diagnostic steps

Click Copy diagnostics on the failed run. Paste the JSON into the ticket. Required fields will already be populated.
The failure_reason field is the primary signal; cross-reference to the table above.
If the failure is provider-side (github_token_*), confirm in the Integrations page whether the underlying OAuth token is still present and not expired.
If the failure is in the test step, inspect timeline_tail for test_runner_output events to see the last command + stderr.

Rollback / cleanup behavior

The template’s rollback_or_cleanup_behavior says: “Aborts the PR draft if creation has not completed; closes the working branch on the runner. Does not force-push or delete the source branch.” That means:

Killing the run mid-flight leaves no PR open on GitHub.
The agent’s working branch on the runner is deleted on cleanup.
The customer’s main/source branches are never touched.

Escalation

If the failure reason is not in the table OR the customer reports a PR was created with the wrong content, ping platform-runners in Slack with the run ID and the diagnostics bundle. Do not retry the template without confirmation.