ADR-081: GitHub identity — whose token serves a request, which app mints it, and who else may act

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).

Context

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):

Decision

D1: A request is served as its account, and only as its account

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):

D2: A hosted deploy has no GitHub identity of its own

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.

This closes #2123’s last unread leg (a “system” keychain row) structurally rather than by a database count.

D3: One published Piper GitHub App mints the user’s grant (user-to-server tokens)

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:

Condition (the compatibility check, before any build):

  1. The deployed 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.
  2. Our native REST reads (milestones, labels, the native-path list) do the same.

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.

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:

How the token expires and refreshes (the check’s item 4):

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.

D4: The user’s own PAT stays a supported leg

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.

D5: Installation (server-to-server) tokens never serve a user’s request

#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.

D6: Agent seats have their own identity, separate from the product’s

The cohort’s agent seats act on the repository through a separate GitHub App, the seats app (#2136, approved by xian 10-21).

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.

D7: Multiple installations are native to D3, and the rest stays Enterprise

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.

What each issue becomes

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.

Consequences

Positive:

Negative:

Not changed:

Verified how

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.