GitHub integration

What it gives Plexward

Tracker items. Open issues in an entity's repo become that entity's open items on the dashboard board, with priority, status and a link back.
Brain sync. Each entity's brain is a git repo. GitHub is where it is backed up, where a second machine picks it up, and where history lives.
Briefings. The daily and weekly briefs read the brain's git log to answer "what actually changed for this entity in the last 24 hours".
Skills. Anything that opens a pull request, reviews a diff, or files an issue from a session runs through gh.

Layer

cli. It is machine-wide: gh holds one authenticated identity, used by every entity. There is no per-entity GitHub credential, and that is fine, because isolation here is repo-level rather than account-level.

Declare it as:

{ "name": "GitHub", "layer": "CLI/API", "svc": "Issues · Repos", "account": "acme org (@you)" }

The CLI/API layer is not probeable by claude mcp list, so bin/mc-connectors special-cases the name GitHub and probes it with gh auth status instead.

Prerequisites

The gh CLI installed and on PATH.
A GitHub account with access to the org or user that owns the entity repos.
Decide up front whether entity brains are private repos in an org or private repos under your personal account. Moving them later is possible but rewrites every remote.

Setup steps

1. Authenticate once per machine.

gh auth login --hostname github.com --git-protocol ssh --web

Choose SSH unless you have a reason not to: the brain-sync script pushes non-interactively from cron, and an HTTPS token that expires will fail silently at 03:00.

Scopes worth having: repo (required), read:org (so gh repo create can see your orgs), project if you intend to read GitHub Projects, gist if any skill writes gists. Add one later with:

gh auth refresh -h github.com -s project

2. Create the entity's brain repo.

cd ~/brains/acme-brain
git init && git add -A && git commit -m "init: acme brain"
gh repo create acme-org/acme-brain --private --source=. --remote=origin --push

Keep this behind an explicit confirmation in any automated flow. gh repo create is outward-facing and awkward to undo.

3. Declare it and pick the tracker repo. In catalog/declarations.json, add the entry above. In the entity's registry record, set the tracker source to github and name the repo, so the items refresh knows where to look.

4. Register it for sync. Add the new brain to your brain-sync script so it is pulled and pushed with the rest.

Per-entity routing

gh sees every repo you can see, so routing is about which repo an entity's agent is allowed to touch. In <brain>/integrations/mcp-routing.md:

## Owned Integrations
| MCP Tool | Service | Account / Workspace | Notes |
|---|---|---|---|
| GitHub (`gh`) | Issues, Repos | acme-org | Tracker repo: `acme-org/acme-brain`. |

## NOT This Company
- Any repo outside `acme-org`. Do not open issues or PRs in another entity's
  repo from this session.

Two practical rules that have earned their place:

One tracker repo per entity. If an entity has both a brain repo and a product repo, say explicitly which one carries the open items, or the board will show two different realities.
A frozen repo stays frozen. When an entity moves its issues from one repo to another, write the old repo into NOT This Company with the date. An agent reading stale issues produces a confidently wrong brief.

Verify

gh auth status
gh issue list --repo acme-org/acme-brain --state open --limit 5
bin/mc-connectors --company acme --dry-run

Expected: gh auth status prints Logged in to github.com account <you>, and the connector row for GitHub reports active with a gh account <you> detail.

Common failures

gh not authenticated after a reboot or a new shell. The credential is per-user, not per-shell, but a cron or pm2 process running as a different user has no credential at all. If loops push from cron, confirm the cron user is the same user that ran gh auth login.
Missing scope surfaces as a 404, not a 403. GitHub hides repos you cannot see. If gh repo create cannot find your org or an issue list comes back empty for a repo you know exists, suspect scopes before suspecting the repo name.
A repo with hundreds of open issues floods the board. Filter by label before you take the top N, otherwise the entity's items become noise and the briefing follows them. Label conventions beat raw recency.
HTTPS token expiry in headless runs. The push succeeds interactively and fails from cron. This is why the setup step picks SSH.
An entity added to the registry but not to the sidebar data file stays invisible. That is an onboarding bug, not a GitHub one, but it presents as "GitHub is connected and nothing shows up".

What Plexward does with it once connected

The items refresh runs gh issue list --repo <repo> --state open --json number,title,url per entity, keeps roughly the top eight, and writes them into the dashboard's items file as #<number> <title> with a link. Priority comes from labels where you use them.

The daily brief reads the brain repo's git log, filtered to exclude churn commits, to describe what moved. The weekly digest does the same over seven days. Review loops open pull requests against the entity's repos and never merge them: merging is a human step, by design.

GitHub