Status: ACCEPTED, 2026-10-24 (Arch-authored, on xian’s go-ahead in the Production-map rulings, 2026-10-24 17:28: “one ADR on GitHub identity”). D3 is accepted on the condition that its compatibility check passes; if it fails, D3’s fallback governs. 2026-11-11: the condition is met (Arch, from #2174’s two runs); D3 governs and the fallback does not apply. See “D3’s check, result” under D3. Finding F5 in docs/internal/planning/production-map-review-round2-2026-10-23.md.
Amends: ADR-070 D3 and Amendment B (this ADR is the identity half; Amendment B stays the resolver half).
Related issues: #1966, #2123, #1514 (GitHub part), #1325, #2136, #1061, and #2151 (the is_available() ruling, 10-24 16:49).
Six issues across three sprints each decide part of one question: when Piper touches GitHub, whose identity is acting, and which app minted that identity’s token? Separately they disagree.
What exists today, from source (10-24):
services/mcp/consumer/github_oauth_handler.py, “OAuth 2.0 authorization-code flow for a GitHub OAuth App”).
GITHUB_OAUTH_CLIENT_ID/_SECRET, else the keychain.["repo"], which is full read/write on every repo the user can reach (“confirm minimal set” is still open in the code).user_api_keys, then the keychain.GitHubConfigService.get_authentication_token("system") falls back to env GITHUB_TOKEN and the related names, then to a “system” keychain row, with no hosted guard. On alpha none of those names is set (PA’s names-only read, 10-20). The fix for #2123 (dedbe6e3ad) stopped principal-bearing reads from using it, but the fallback itself remains.mediajunkie) when they push and edit on GitHub (#2136).Every GitHub read or write made for a request uses the requesting account’s own credential, resolved by the one resolver (resolve_credential, ADR-070 B1–B2). There are no exceptions for a session configured earlier, for another principal or for the deployment.
This is #2121’s rule and #2123’s ruling made general. It is the reason D5 rejects installation tokens for user work.
Status follows the resolver (Amendment B4, extended 10-24):
is_available() takes its answer from resolve_credential.GitHub has the same rule as the LLM key (PDR-005 Amendment 1 §2, “Piper never spends an operator’s key”): on a hosted deploy, no GitHub credential belongs to the deployment.
not is_hosted_deployment(), which means a local install, where the operator is the user.get_authentication_token("system") returns None by construction, and a principal-less caller gets no GitHub.This closes #2123’s last unread leg (a “system” keychain row) structurally rather than by a database count.
The classic per-deployment OAuth App is replaced by one GitHub App, published by Piper Morgan. Its user access tokens (“user-to-server”) are the OAuth leg’s grant.
Why a GitHub App and not a published OAuth App:
repo’s full control: Issues and Pull requests read/write, Contents read, Metadata read. Add more only when a feature needs it, recorded in this ADR.error field) maps to STALE_TOKEN; a refresh that could not complete (timeout, connection failure, 5xx) maps to UNREACHABLE and leaves the stored pair untouched; neither maps to CONNECT_REQUIRED (Arch, 2026-11-11, on CXO’s condition; #2342).Condition (the compatibility check, before any build):
github-mcp-server (v1.5.0 or its successor) serves the read and write tools we call with a GitHub App user access token as its bearer.This is unverified today. Whoever builds it (Lead) checks it first, against a test installation, and records the result in this ADR.
Onboarding copy and the install step’s experience are CXO’s. The app’s registration and the custody of its credentials are HOST’s to record. Owner (Arch, 2026-11-12 13:08, memo 01M78SDJP2DZK5C33SYB4KN8TZ): the org pipermorgan owns the published App, not xian’s personal account, as the classic OAuth Apps have since 11-04. It is registered with install scope “Only on this account” until recipe 11 step 7 widens it. The served rows run on a test repository in the org. Scope corrected (Arch, 2026-11-12 13:24, memo 01M78TA5VY901RVKNJNGACX712): narrow scope is no longer an Arch requirement. At the cutover it would cut off every connected account, including repositories outside the org. “Any account” is safe on trust, because an install grants nothing without a user token from Piper’s Connect flow and the App holds no private key. The scope is xian’s call.
D3’s check, tooling (Lead, 2026-11-04; #2174): scripts/github_app_token_check.py runs the check once a test GitHub App is installed and a user access token exists. It takes the token from GITHUB_CHECK_TOKEN only, calls every github-mcp-server tool Piper uses and the REST reads named above, and prints PASS or FAIL per call and totals, never the token or any body; --writes also creates, comments on and closes one issue in a test repository. The result, tool by tool with the versions tested, is recorded here when it runs.
D3’s check, result (Arch’s validation, 2026-11-11; #2174). Condition met; D3 governs.
services/mcp/consumer/github_adapter.py) calls nine github-mcp-server tools: search_issues, search_pull_requests, search_repositories, list_issues, list_branches, list_releases, issue_read, issue_write (create and update) and add_issue_comment. All nine passed with a GitHub App user access token as the bearer. issue_write create passed on 11-07, when it made the test issue through the App; the rest passed on 11-11 with a refreshed token. _RESOLVE_TOOL (resolve_resource) is a provisional placeholder, not a github-mcp-server tool, and is outside this condition.GET /user, milestones, labels and /user/repos passed.performed_via_github_app set to the test App (Exec’s API read).fly proxy to piper-morgan-gh-mcp, the sidecar both fly.toml and fly.mcp.toml point GITHUB_MCP_SERVER_URL at. Its image is pinned to ghcr.io/github/github-mcp-server:v1.5.0 in deploy/fly/github-mcp.fly.toml. Lead records the running machine’s version alongside the two tables below.D3’s check, the two tables and the versions (Lead, 2026-11-11; #2174). Both runs were xian’s, on Amber, from ~/Development/piper-morgan-product, through fly proxy to piper-morgan-gh-mcp, against the test repository dinp-machine/piper-test-activity with the test App piper-morgan-d3-check. No token, secret or client ID is recorded here.
Run 1, 2026-11-07 16:23 PT, first token, --writes (script at abfe9f115f):
rest GET /user PASS
rest GET milestones PASS
rest GET labels PASS
rest GET /user/repos PASS
narrowing: private repo not installed is refused PASS
search_issues PASS
search_pull_requests PASS
search_repositories PASS
list_issues PASS
list_branches PASS
list_releases PASS
issue_write create FAIL tool-error
--- 12 calls: 11 pass, 1 fail
The one FAIL was the script’s, not the server’s: the create made issue 43 through the App (Exec’s API read at 16:24: created by the test user, performed_via_github_app.slug = piper-morgan-d3-check), and the script then failed to read the new issue’s number from the reply. Fixed in ad35f8325d, which also added --issue N.
Run 2, 2026-11-11 18:52 PT, the refreshed token, --writes --issue 43 (script at ad35f8325d):
rest GET /user PASS
rest GET milestones PASS
rest GET labels PASS
rest GET /user/repos PASS
narrowing: private repo not installed is refused PASS
search_issues PASS
search_pull_requests PASS
search_repositories PASS
list_issues PASS
list_branches PASS
list_releases PASS
issue_write create SKIPPED (--issue 43)
issue_read get PASS
add_issue_comment PASS
issue_write update (close) PASS
--- 15 calls: 14 pass, 0 fail
Versions:
v1.5.0 in deploy/fly/github-mcp.fly.toml. The running machine’s version was not read for either run: no seat runs fly, and the check script did not print the server’s own version until 2026-11-11 (#2341). The read is asked of xian through Exec. Until it is recorded here, “v1.5.0” is the pin, not a measurement.X-GitHub-Api-Version: 2022-11-28, sent by the script on every REST row.How the token expires and refreshes (the check’s item 4):
GET /user. That 401 is explained by the 8-hour expiry alone, so it is not evidence that a refresh revokes the previous access token.scripts/github_app_refresh_check.py (#2341) does the refresh, the old-token 401 check, the proxy and the table as one command with hidden prompts, and its table names the server’s handshake version.error field) maps to STALE_TOKEN; a refresh that could not complete (timeout, connection failure, 5xx) maps to UNREACHABLE and leaves the stored pair untouched; neither maps to CONNECT_REQUIRED (Arch, 2026-11-11, on CXO’s condition; #2342).D3’s build (#2342, 2026-11-12). The unit layer is on main and inert until the App is registered and its secrets are set. Arch’s rulings are on issue 2342 and in decisions.log.
GITHUB_APP_CLIENT_ID and GITHUB_APP_CLIENT_SECRET are both set (services/mcp/consumer/github_app_grant.py). GITHUB_APP_SLUG gives the install link. With App mode off, the classic app behaves as before.github_mcp_oauth row: both tokens, both expiries and minted_by: github_app. A value without the marker is a classic grant and never serves in App mode.services/mcp/consumer/github_app_refresh.py, services/scheduler/github_app_refresh_job.py).connector_bindings.status_reason: cutover or refresh_rejected. The reply is picked by it.scripts/github_app_cutover.py, run in the same sitting as setting the secrets. It is a dry run by default. With --apply, for every stored grant the App did not mint, it tries the revoke at GitHub with the classic app’s credentials, marks the binding stale with cutover, and deletes the token. It leaves personal tokens, saved repository choices and App grants alone, prints counts only, and finds nothing on a second run.scripts/github_app_cutover_sitting.py (#2343): it asks for the App’s client ID, secret and slug (the first two hidden), checks the pair with GitHub, sets the values through fly secrets import on standard input (the slug alone on the MCP app, first), waits for the main app to restart, and runs the cutover dry run, the apply and the dry run again in the container. Two typed yes answers gate the changes. No seat has run it against the hosts; xian’s first run is the check.Amendment B2’s PAT leg stays, with #1966 option (i). It is the user’s own credential, pasted in by them, encrypted at rest and never shared. It serves self-hosting and users who won’t install an app.
#1325’s end state is rejected for user work. An installation token acts as the app, so:
Both break D1. Holding a user token is the price of acting as the user, and D3’s expiring user tokens are the safest form of it. #1325 closes as superseded by D3.
Installation tokens have one legitimate use in this system, D6, and it isn’t a product path.
The cohort’s agent seats act on the repository through a separate GitHub App, the seats app (#2136, approved by xian 10-21).
piper-morgan-product and minted on Amber.The product app (D3) and the seats app never share an app, key or token. The product app never acts for an agent, and the seats app never acts for a user.
The acceptance bar is #2136’s own (HOST): from a seat, .permissions.admin reads false, and a push to ops/restarter is refused.
A GitHub App is installed once per user or org, so D3 already supports many installations for per-user grants. 1.0 needs nothing more. #1061’s workspace-level credential management, shared by an organization’s members, stays Enterprise, and is a bet-gate question.
| Issue | Under this ADR |
|---|---|
| #1966 (two resolvers) | D1: the remaining callers, the is_available() gate included, derive from resolve_credential. Stays the precondition for sprint H (F15). |
| #2123 (deployment token on activity reads) | D1 fixed it in dedbe6e3ad; D2 removes the remaining leg by construction. Closes when the D2 gate and its pin land. |
| #1514 (published apps), GitHub part | D3. Calendar and Notion stay in #1514; Slack’s part is Fast Follow. |
| #1325 (installation-token auth) | D5: superseded by D3; close with a pointer here. |
| #2136 (seat identity) | D6: unchanged in shape, recorded as architecture. |
| #1061 (multi-installation) | D7: Enterprise, unchanged. |
PPM files the one tracking issue F5 asks for, “GitHub identity: one app/token model and whose token serves a read”, which links these six. Build order inside it is Lead’s: D2’s gate, then D1’s gate convergence (#1966 and #2151), then D3’s check, then D3.
Positive:
Negative:
RESOURCE_NOT_FOUND), never “no issues”.Not changed:
Read github_oauth_handler.py (L40–215: the classic OAuth App, the repo scope, no refresh), config_service.py get_authentication_token (L127–208: the “system” env and keychain fallback, no hosted guard), github_adapter.py resolve_credential and its PAT legs (L1428–1506), ADR-070 D3 and Amendment B, CONNECTORS.md’s GitHub row, and the six issues’ bodies and latest comments.
Layer: source and documents. D3’s compatibility with github-mcp-server is unverified and is stated as its condition.
Denominator: GitHub only; 6 of the 6 issues F5 names are mapped.