GitHub Issues Plugin

What It Does

@agentxchain/plugin-github-issues mirrors governed run state into one configured GitHub issue.

It listens to:

• after_acceptance
• on_escalation

and updates:

• one plugin-owned comment per run
• managed AgentXchain labels for phase or blocked state

Install

Install by short name (recommended):

agentxchain plugin install github-issues \
  --config '{"repo":"owner/name","issue_number":42}'

Config

{
  "repo": "owner/name",
  "issue_number": 42,
  "token_env": "GITHUB_TOKEN",
  "api_base_url": "https://api.github.com",
  "label_prefix": "agentxchain"
}

Required fields

• repo GitHub repository in owner/name form.
• issue_number Issue number to mirror into.

Optional fields

• token_env Environment variable that contains the GitHub token. Defaults to GITHUB_TOKEN.
• api_base_url API base URL override for GitHub Enterprise or test servers.
• label_prefix Prefix for labels managed by the plugin. Defaults to agentxchain.

Runtime Behavior

• The plugin reads the hook envelope from stdin.
• It upserts one comment per run_id using a stable marker.
• On after_acceptance, it syncs:
  • <label_prefix>
  • <label_prefix>:phase:<phase>
• On on_escalation, it syncs:
  • <label_prefix>
  • <label_prefix>:blocked
• It preserves non-AgentXchain labels already on the issue.

Failure Semantics

• Advisory only.
• Missing or invalid plugin config returns warn.
• Missing token env returns warn.
• GitHub API failures return warn.

Proof Surfaces

The github-issues plugin has two levels of proof:

Continuous subprocess proof

cli/test/e2e-builtin-github-issues.test.js — installs the plugin by short name into a temp governed project, runs a governed flow with mock local runtimes, and verifies that the plugin hooks are invoked and produce correct advisory verdicts. Runs in CI without GitHub credentials.

Live product-example proof

examples/governed-todo-app/run-github-issues-proof.mjs — runs a real 3-role governed agentxchain run with the github-issues plugin installed, targeting issue #77. After the run completes, verifies via GitHub API that the plugin posted a comment with the run marker and synced managed labels.

Recorded case study (2026-04-13):

Field	Value
Run ID	run_c2b690192eade09a
Plugin source	builtin:github-issues
Roles	pm → dev → qa
Accepted turns	3
Decision ledger	7 entries
Cost	$0.019
Comment	#issuecomment-4240678624
Labels	agentxchain, agentxchain:phase:qa

Boundaries

• This plugin does not close issues.
• It does not claim post-gate approval or completion because the shipped hook surface has no post-gate callback.
• It binds one plugin install to one GitHub issue. Multi-issue routing is not part of the shipped contract.