<?xml version="1.0" encoding="utf-8"?>
<entry xmlns="http://www.w3.org/2005/Atom" xml:base="https://docs.spec-kitty.ai/adr/3.x/2026-04-06-3-github-app-installation-authority/">
  <id>https://docs.spec-kitty.ai/adr/3.x/2026-04-06-3-github-app-installation-authority/</id>
  <title>ADR: GitHub App Installation Identity Is Provider-Authoritative; Nango Is Secondary</title>
  <updated>2026-04-06T00:00:00.000Z</updated>
  <author><name>Spec Kitty</name></author>
  <link rel="alternate" type="text/html" href="https://docs.spec-kitty.ai/adr/3.x/2026-04-06-3-github-app-installation-authority/"/>
  <summary>Accepted ADR making GitHub App installation identity provider-authoritative and Nango secondary for connector binding and resource-mapping decisions.</summary>
  <content type="html">&lt;span id=&quot;adr-github-app-installation-identity-is-provider-authoritative-nango-is-secondary&quot;&gt;&lt;/span&gt;
&lt;p&gt;&lt;strong&gt;Status&lt;/strong&gt;: Accepted
&lt;strong&gt;Date&lt;/strong&gt;: 2026-03-10
&lt;strong&gt;Author&lt;/strong&gt;: Spec Kitty team + Codex
&lt;strong&gt;Related ADR&lt;/strong&gt;: &lt;a href=&quot;/adr/3.x/2026-04-06-2-connector-auth-binding-separation/&quot;&gt;Connector Installation, User Link, and Resource Mapping Separation&lt;/a&gt;&lt;/p&gt;
&lt;h2 id=&quot;context&quot;&gt;Context&lt;/h2&gt;
&lt;p&gt;The connector hard-cutover introduces installation-first integrations across providers. During planning, one ambiguity kept recurring:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;should Spec-Kitty treat a Nango &lt;code dir=&quot;auto&quot;&gt;connection_id&lt;/code&gt; as the canonical identity for a GitHub App installation?&lt;/li&gt;
&lt;li&gt;or should Spec-Kitty treat GitHub’s own installation identifier as the source of truth and only use Nango as an optional credential helper?&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;This distinction matters because GitHub Apps are not shaped like ordinary workspace OAuth connections.&lt;/p&gt;
&lt;p&gt;GitHub’s provider-native model is:&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;One GitHub App registration has one webhook configuration&lt;/li&gt;
&lt;li&gt;Each customer install creates a GitHub &lt;strong&gt;installation&lt;/strong&gt;&lt;/li&gt;
&lt;li&gt;Webhook payloads for GitHub App events include the &lt;strong&gt;installation&lt;/strong&gt; object&lt;/li&gt;
&lt;li&gt;Installation access tokens are minted &lt;strong&gt;for a specific installation ID&lt;/strong&gt;&lt;/li&gt;
&lt;li&gt;Optional user-to-server tokens are separate from the shared installation and only apply when the app needs to act on behalf of a user&lt;/li&gt;
&lt;/ol&gt;
&lt;p&gt;That means GitHub itself recognizes installation identity and webhook authenticity independently of any Nango-side connection naming.&lt;/p&gt;
&lt;p&gt;If Spec-Kitty incorrectly treats the Nango &lt;code dir=&quot;auto&quot;&gt;connection_id&lt;/code&gt; as the primary authority, agents will keep making the same design mistakes:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;routing inbound webhooks through Nango identifiers instead of GitHub installation identity&lt;/li&gt;
&lt;li&gt;storing GitHub install state as if it were generic OAuth workspace state&lt;/li&gt;
&lt;li&gt;coupling app-level webhook verification to team-level or mapping-level secrets&lt;/li&gt;
&lt;li&gt;designing future migrations around renaming Nango connections instead of persisting provider-native identifiers&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;decision&quot;&gt;Decision&lt;/h2&gt;
&lt;p&gt;For GitHub App integrations, &lt;strong&gt;GitHub provider identity is authoritative&lt;/strong&gt;.&lt;/p&gt;
&lt;p&gt;Spec-Kitty must model GitHub App installations as follows:&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;provider_installation_id&lt;/code&gt; is the canonical external identity of a GitHub installation&lt;/li&gt;
&lt;li&gt;GitHub webhook verification uses the &lt;strong&gt;app-level webhook secret&lt;/strong&gt; configured on the GitHub App registration&lt;/li&gt;
&lt;li&gt;Inbound webhook routing resolves from the payload’s &lt;code dir=&quot;auto&quot;&gt;installation.id&lt;/code&gt; and repository identity to a local installation plus repo mapping&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;control_plane_connection_id&lt;/code&gt; is optional and secondary; if Nango is used, it is an implementation detail for outbound credential retrieval, not the canonical installation key&lt;/li&gt;
&lt;li&gt;Optional user-level GitHub authorization is a separate concern from the shared installation and should be modeled like a user link, not as the installation itself&lt;/li&gt;
&lt;/ol&gt;
&lt;h2 id=&quot;rules-for-agents&quot;&gt;Rules For Agents&lt;/h2&gt;
&lt;p&gt;When working on GitHub App design or implementation, agents must follow these rules:&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;Never use Nango &lt;code dir=&quot;auto&quot;&gt;connection_id&lt;/code&gt; as the sole or primary identifier for a GitHub App installation&lt;/li&gt;
&lt;li&gt;Always persist GitHub’s installation identity on the installation record&lt;/li&gt;
&lt;li&gt;Treat webhook URL and webhook secret as &lt;strong&gt;app-level&lt;/strong&gt; configuration, not per-team or per-mapping state&lt;/li&gt;
&lt;li&gt;Route GitHub events by &lt;code dir=&quot;auto&quot;&gt;installation.id&lt;/code&gt; plus repository identity, then resolve explicit repo mapping&lt;/li&gt;
&lt;li&gt;Treat repo mappings as the routing authority; Git metadata may suggest mappings but does not replace them&lt;/li&gt;
&lt;li&gt;Keep user-to-server tokens separate from installation-to-server auth&lt;/li&gt;
&lt;/ol&gt;
&lt;h2 id=&quot;implementation-consequences&quot;&gt;Implementation Consequences&lt;/h2&gt;
&lt;h3 id=&quot;data-model&quot;&gt;Data model&lt;/h3&gt;
&lt;ul&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;TeamServiceInstallation.provider_installation_id&lt;/code&gt; is required for GitHub&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;TeamServiceInstallation.control_plane_connection_id&lt;/code&gt; must be nullable&lt;/li&gt;
&lt;li&gt;repo access and explicit repo mappings live beneath the installation&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;webhooks&quot;&gt;Webhooks&lt;/h3&gt;
&lt;ul&gt;
&lt;li&gt;GitHub App ingress should be an app-level endpoint, not a binding-specific or team-specific endpoint&lt;/li&gt;
&lt;li&gt;signature validation uses the app webhook secret&lt;/li&gt;
&lt;li&gt;payload handling must extract &lt;code dir=&quot;auto&quot;&gt;installation.id&lt;/code&gt; and repository identity before local routing&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;outbound-github-api-calls&quot;&gt;Outbound GitHub API calls&lt;/h3&gt;
&lt;ul&gt;
&lt;li&gt;the default authority chain is:
&lt;ul&gt;
&lt;li&gt;app private key / app auth&lt;/li&gt;
&lt;li&gt;GitHub &lt;code dir=&quot;auto&quot;&gt;installation_id&lt;/code&gt;&lt;/li&gt;
&lt;li&gt;installation access token minted for that installation&lt;/li&gt;
&lt;/ul&gt;
&lt;/li&gt;
&lt;li&gt;if Nango is used, it may help acquire or manage outbound credentials, but it does not replace the provider installation identifier in Spec-Kitty’s domain model&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;user-links&quot;&gt;User links&lt;/h3&gt;
&lt;ul&gt;
&lt;li&gt;user links are only needed for user-attributed operations&lt;/li&gt;
&lt;li&gt;user links must not replace shared installation state&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;alternatives-considered&quot;&gt;Alternatives Considered&lt;/h2&gt;
&lt;h3 id=&quot;treat-nango-connection_id-as-the-canonical-github-installation-identity&quot;&gt;Treat Nango &lt;code dir=&quot;auto&quot;&gt;connection_id&lt;/code&gt; as the canonical GitHub installation identity&lt;/h3&gt;
&lt;p&gt;Rejected.&lt;/p&gt;
&lt;p&gt;This hides the provider-native installation boundary and makes inbound routing dependent on an internal control-plane key that GitHub does not send on webhook payloads.&lt;/p&gt;
&lt;h3 id=&quot;treat-github-app-install-as-ordinary-workspace-oauth&quot;&gt;Treat GitHub App install as ordinary workspace OAuth&lt;/h3&gt;
&lt;p&gt;Rejected.&lt;/p&gt;
&lt;p&gt;GitHub App auth and webhook flow are installation-based, not simple workspace-token based.&lt;/p&gt;
&lt;h3 id=&quot;put-webhook-secret-on-each-repo-mapping&quot;&gt;Put webhook secret on each repo mapping&lt;/h3&gt;
&lt;p&gt;Rejected for GitHub App.&lt;/p&gt;
&lt;p&gt;GitHub App webhook verification is configured at the app registration boundary. Repo mappings are downstream routing state, not webhook-auth boundaries.&lt;/p&gt;
&lt;h2 id=&quot;operational-guidance&quot;&gt;Operational Guidance&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;Forced reconnect or reinstall flows must preserve the distinction between:
&lt;ul&gt;
&lt;li&gt;GitHub installation identity&lt;/li&gt;
&lt;li&gt;optional Nango connection identifiers&lt;/li&gt;
&lt;li&gt;optional user authorization&lt;/li&gt;
&lt;/ul&gt;
&lt;/li&gt;
&lt;li&gt;Migration planning must assume that old Nango connection naming can change without redefining what the GitHub installation is&lt;/li&gt;
&lt;li&gt;Observability should log both local installation UUID and &lt;code dir=&quot;auto&quot;&gt;provider_installation_id&lt;/code&gt; for GitHub events&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;references&quot;&gt;References&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;&lt;a href=&quot;https://docs.github.com/apps/creating-github-apps/registering-a-github-app/registering-a-github-app&quot;&gt;GitHub Docs: Registering a GitHub App&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;&lt;a href=&quot;https://docs.github.com/en/apps/creating-github-apps/authenticating-with-a-github-app/authenticating-as-a-github-app&quot;&gt;GitHub Docs: Authenticating as a GitHub App&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;&lt;a href=&quot;https://docs.github.com/en/apps/creating-github-apps/authenticating-with-a-github-app/generating-an-installation-access-token-for-a-github-app&quot;&gt;GitHub Docs: Generating an installation access token for a GitHub App&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;&lt;a href=&quot;https://docs.github.com/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-user-access-token-for-a-github-app&quot;&gt;GitHub Docs: Generating a user access token for a GitHub App&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;&lt;a href=&quot;https://docs.github.com/enterprise-cloud%40latest/developers/webhooks-and-events/webhooks/webhook-events-and-payloads&quot;&gt;GitHub Docs: Webhook events and payloads&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;&lt;a href=&quot;https://docs.nango.dev/integrations/all/github-app&quot;&gt;Nango Docs: GitHub App&lt;/a&gt;&lt;/li&gt;
&lt;/ul&gt;</content>
</entry>
