Github Poller

github-poller — watch GitHub repos for activity

This is an opt-in poller skill that ships with mimir under mimir/optional-skills/ but is NOT auto-installed. Most installs won't watch a GitHub repo, so the framework doesn't seed it by default.

Installation

1. Copy the directory into your agent home:

   cp -r mimir/optional-skills/github-poller <home>/skills/
   

   (Or run from inside the container against /workspace/mimir.)

2. Configure env vars:

   Variable	Required	Description
   GITHUB_REPOS	yes	Comma-separated owner/repo list (e.g. jasoncarreira/mimir,jasoncarreira/mimirbot)
   GITHUB_TOKEN	recommended	GitHub PAT. Falls back to gh auth token when unset.
   MIMIR_GITHUB_SELF_LOGIN	optional	GitHub login mimir authors as. Events from this login get filtered out (mimir doesn't wake itself). Leave empty if mimir uses the operator's PAT — the operator is the signal you want, not the noise.

   These env vars must be exported in mimir's process environment (e.g. via the container's env file). The framework gates subprocess env keys two ways: a built-in allowlist (PATH, HOME, locale, XDG, CA bundles — everything else is stripped) plus a deny filter on top (*_TOKEN, *_SECRET, *_API_KEY, *_PASSWORD, MIMIR_* are stripped even if allowlisted). The pass_env field in this skill's pollers.json declares all three keys above as explicit pass-throughs, bypassing both gates — different mechanism per key:

   • GITHUB_TOKEN — matches *_TOKEN deny pattern → pass_env bypasses the deny filter.
   • MIMIR_GITHUB_SELF_LOGIN — matches MIMIR_* deny pattern → pass_env bypasses the deny filter.
   • GITHUB_REPOS — not a secret, but not in the built-in allowlist either → pass_env bypasses the allowlist gate. Same end result (key reaches the subprocess), just gated differently. If you rename or relocate a var, update pollers.json accordingly. GITHUB_TOKEN set but not declared in pass_env → silently absent in the subprocess → poller falls through to gh auth token → zero events forever if gh isn't authed.

3. Bring it live:

   reload_pollers
   # → "reload_pollers ok: N poller(s) registered — github-activity, ..."
   

   (Or restart the container; pollers are auto-loaded at startup.)

What it watches

For each repo in GITHUB_REPOS:

• New issues opened (since last poll)
• New pull requests opened
• New issue comments (covers both issue + PR conversation comments)
• New PR review comments (inline diff comments — distinct from conversation comments)
• New PR reviews (approve / changes-requested / commented with body)
• PR pushes/updates (pr_synchronize) — new commits pushed to an existing open PR. The poller calls GET /repos/{repo}/compare/{prev}...{new} to fetch up to 3 commit subjects inline. If multiple commits land between polls, all are surfaced (total count + first 3 subjects + "… N more" when truncated). Force-pushes that change the SHA but not the diff also fire — this is a known false-positive; compare-diff diffing on every poll is too expensive.
• Review requests (pr_review_requested) — fired when MIMIR_GITHUB_SELF_LOGIN appears in a PR's requested_reviewers. State-reconciling retry (chainlink #299): a submitted review removes you from requested_reviewers, so while you remain requested the poller RE-EMITS once per poll (up to REVIEW_REQUEST_MAX_ATTEMPTS, default 3). This recovers a review whose triggered turn died (e.g. a transient model 503) instead of silently dropping it — the old emit-once model advanced the cursor past a dead turn and never re-fired (observed on PR #511). On exhaustion it emits a one-shot pr_review_request_gave_up signal (no turn; surfaces as a negative algedonic signal via feedback.classify's *_gave_up rule) and goes dormant for that PR until you're removed and re-requested. If an operator re-requests you after you already submitted a substantive review (APPROVED, CHANGES_REQUESTED, or COMMENTED) at the current head SHA, the poller treats that request as satisfied and suppresses both retry emits and give-up signals.
• Stale changes-requested on your own PRs (pr_changes_requested_stale) — state-reconciling reminder (chainlink #449), the reverse direction of the above: reviews ON your PRs are otherwise edge-triggered only, so a turn that reads a request-changes review without pushing fixes loses the work signal when the cursor advances. Each poll, your open PRs whose latest substantive review per reviewer is CHANGES_REQUESTED and whose reviewed diff has not materially changed are reminded on an hourly elapsed-time cadence, with a one-minute allowance for per-run timestamp jitter. Polls before the interval expires do not refresh the timestamp. A substantive fix, later approval clearing all blocking reviews, or PR close/merge stops reminders; a content-free rebase with the same patch does not. Reminder emissions use a bounded attempt series and a one-shot give-up signal; because queued emissions are not proof of delivery, an unchanged unresolved PR starts a fresh series after a 24-hour backstop rather than staying silent forever.
• Mergeability of your own PRs — GitHub's per-PR mergeable result is reconciled with the declared base/head comparison. A clean branch behind its base emits pr_mergeability_rebase, which uses the existing scoped checkout, rebases onto the declared base, runs tests, and pushes with a lease against the observed head. The automatic path is restricted to PRs with no blocking CHANGES_REQUESTED review, so moving the head cannot silently discharge unaddressed feedback. A conflict emits pr_mergeability_conflicting; its scope cannot push and the turn must reproduce the conflict, name all unmerged paths and the base SHA, then abort and escalate. A null mergeability result is asynchronous/unknown and is never acted upon. Attempts use hourly backoff, are bounded per PR/head/reason, and end in the named pr_mergeability_rebase_gave_up signal. At most one such attempt is emitted across all repositories in a poll cycle. This path never merges a PR.
• Completed check failures on open PRs (pr_ci_failure) — a newly failed check set on a PR authored by MIMIR_GITHUB_SELF_LOGIN starts one remediation turn bound to the repository, PR number, immutable head SHA, failed check IDs, names, conclusions, and log URLs. The repository checkout preflight re-fetches the PR and checks and stops before mutation when the PR closed, the head was superseded, or a rerun is green. Failures on external contributors' PRs emit a pr_ci_failure_external notification signal only and never receive repository mutation authority. CI remediation retains pr_comment authority so blocked or failed repairs can leave an operator-visible trace, but excludes pr_edit and pr_rerequest. Stable delivery keys and framework receipts dedupe overlapping polls while allowing a rejected handoff to retry safely. On rollout, a head whose failures predate the first observation is deliberately baselined and remains quiet until its head or failure set changes. Open-PR discovery is intentionally bounded to the 100 most recently updated PRs; a newly completed check normally refreshes the affected PR into that window.

Issue / PR / comment / review detection is filtered by created_at > cursor and (when set) user.login != MIMIR_GITHUB_SELF_LOGIN. Push + review-request detection are state-based (head-SHA delta / requested_reviewers membership), not created_at-windowed.

What it doesn't watch (deliberate)

• Commits — already handled by git pull. No GitHub-API path for "new commit" wakes today.
• Issue/PR state changes (close, reopen, merge, label) — adds noise; revisit if it becomes useful.
• Main-branch workflow failures — remain the separate github-ci-watch responsibility; this poller only handles checks attached to open PR heads.
• Notifications API (/notifications) — an alternative path that's higher-noise; this poller takes the targeted-endpoint approach instead.

Why login-based, not email-based

GitHub's API events expose user.login for issues, PRs, comments, and reviews — never the author's commit email. Email-based filtering (e.g. noreply@mimir-agent.local) is the right key for commits but not for the API surface.

Cost

Polling 1 repo every 15 min @ 4 endpoints = ~16 calls/hr/repo. For a 5-repo watch that's ~80/hr — well under GitHub's 5000/hr per-PAT rate limit. The since= query param keeps each call's payload small.

Batching

pollers.json sets batch_size=1: each independent GitHub item gets its own turn and full tool budget. This deliberately avoids combining multiple PR reviews or remediations into one turn whose shared budget can strand later items. Tune only with care: larger batches reduce turn count but couple unrelated GitHub work to one execution budget.

Cursor file

Persists at <home>/state/pollers/github-activity/cursor.json (the framework-injected STATE_DIR). Survives container rebuilds. First run looks back 1 hour to bound the backfill burst.

The pr_changes_requested key maps {repo: {pr_number: {"head_sha": sha, "last_reminded_at": ISO-8601 UTC timestamp, "attempts": count}}}. It tracks unresolved own-PR stale states, the hourly reminder floor, and bounded attempt series while the live snapshot remains semantically blocked. Attempts are charged from framework-written turn outcomes, not reminder emission. Authorization and tool-boundary refusals are reported but exempt from the content-failure budget and retry only at the 24-hour backstop, preventing a permanent configuration fault from firing at poll cadence. At the cap it emits one pr_changes_requested_gave_up signal with the charged outcome reasons; a head change re-arms immediately, and an unchanged parked entry re-arms after the same 24-hour delivery-loss backstop. Closed, unblocked, or substantively changed PRs drop out. Pre-cadence bare-string and structured-without-attempts entries migrate quietly as attempt 1 with last_reminded_at set to that poll's time, preventing an upgrade-time emit storm.

The pr_review_requests key maps {repo: {pr_number: attempts}} — attempts counts pr_review_requested emits while you stayed requested (chainlink #299; a dormant PR that gave up parks at cap + 1). The pre-#299 bare-list format ({repo: [pr_number, ...]}) migrates automatically on first load.

The pr_mergeability key maps {repo: {pr_number: {head_sha, reason, last_attempt_at, attempts}}}. A new head or changed failure reason starts a fresh bounded series; current and closed PRs drop out during snapshot rebuild.

The pr_ci_failures key maps each live red PR to its immutable head, stable failure-set delivery key, and last emit time. Framework acknowledgements live in <home>/state/pollers/github-activity/.delivery-receipts/; a receipt is created only after enqueue or external-signal logging succeeds. A missing receipt makes the same claim retry-eligible after five minutes, while atomic files under .delivery-claims/ suppress concurrent poll overlap.

Disabling temporarily

• Unset GITHUB_REPOS — the poller exits silently.
• Or set the cron in pollers.json to a far-future expression.
• Or remove the skill directory: rm -rf <home>/skills/github-poller/ + reload_pollers.

Debugging