Support every GitHub App installation #2404

Problem

The GitHub plugin works with only one GitHub App installation. That installation is set by GITHUB_INSTALLATION_ID. Repositories in any other installation of the same App do not work.

Example from prod: an event automation for fairsource/fair.io never ran. The App is installed on the fairsource org with access to all of its repositories. But prod is configured with the getsentry installation, so:

• The webhook handler drops every fairsource delivery with 202 Ignored.
• Every token Junior creates is for the getsentry installation. Lookups, reactions and agent actions on fairsource/fair.io fail.
• Saving the trigger succeeds and shows it as available, so nothing tells the user that it can never run.

How Junior differs from other GitHub Apps

Most GitHub Apps choose the installation from context before they call the API:

• Event handlers (Probot and similar) use installation.id from the webhook payload for all work on that event.
• Apps with stored records (Vercel, Sentry's GitHub integration) save the installation ID when a user connects an org or imports a repo.
• Repo-only callers call GET /repos/{owner}/{repo}/installation once and keep the result.

Junior also routes raw gh and git traffic from the agent through host egress, one request at a time. The host sees every request, and almost every request names its owner:

• REST /repos/{owner}/{repo}/... and /orgs/{org}/...
• Git smart HTTP github.com/{owner}/{repo}.git
• gh GraphQL reads, which send owner and repo or name variables (cli/cli api/queries_pr.go, api/queries_repo.go)
• Host tools, which already put owner/repo in the egress operation for GraphQL mutations

The credential contract does not depend on the conversation. SandboxEgressCredentialContext.conversationId is telemetry only, and installation leases are shared across all sandboxes. So we route by owner for each request, and do not bind an installation to a conversation.

Plan

1. Webhooks: use the installation that sent the delivery

• Remove the installation ID check. The webhook secret belongs to the App, so a valid signature proves the delivery is for one of its installations.
• Use installation.id from the signed payload for all follow-up requests of that delivery: PR commits, opener and author filters, check suites and reactions.
• Ignore a delivery that has no installation.

2. Egress: route by owner, not by repository

An App can be installed at most once per account. So the owner identifies the installation.

• Installation map: load GET /app/installations, signed as the App, into the plugin cache as account login → installation id. Refresh it when an installation or installation_repositories webhook arrives. Keep a TTL as a backstop.
• Target: grantForEgress finds the owner from the URL path, GraphQL owner variable, or host tool operation. The grant leaseScope is owner:<login> (lowercase). So there is one remembered lease per installation and grant, the same as today for getsentry.
• Default installation: the installation on the account that owns the App. It is in the same map. Use it for reads that name no owner, and for reads of owners where the App is not installed (public repositories).
• Writes: a write to an owner with no installation fails with The GitHub App is not installed on <owner>. It never falls back to another installation.
• Tokens: write tokens keep the full installed permissions. Read tokens keep the read-only permissions of their own installation. Tokens are not limited to one repository, because the lease is per owner.
• Host tools: read requests that use only a node ID, such as the review-thread lookup in resolve-pull-request-review-thread.ts, put owner/repo in operation, as the mutations already do.

3. Config and docs

• Remove GITHUB_INSTALLATION_ID and the installationIdEnv option as a hard cutover. Only the App ID, private key and webhook secret stay.
• Update SETUP.md, the GitHub plugin docs, .env.example files, tests and eval fixtures.
• Document the limit: requests that name no owner use the default installation.

4. Trigger checks

• Saving a GitHub trigger or Watch for an owner with no installation fails with a plain error.
• Core has no async plugin hook for this today. Add the smallest provider-neutral hook to plugin events, for example checkResource({ resourceType, identifier }), which returns a problem message. Call it from event automation create and edit, and from watchEvents.
• With the installation map, the GitHub check is a cache read.

5. junior-prod

• After release, remove the GITHUB_INSTALLATION_ID env var.

Decisions

• No allowlist by installation or org. The App is private, so only orgs we choose can install it. Junior accepts every installation of the App.
• A token is used only for its own installation. A request for an owner in one installation never uses another installation's token. Only reads for owners with no installation use the default installation.
• Route by owner, not by conversation. A conversation can touch more than one org, and the credential contract does not depend on the conversation.
• Owner, not repository. A per-repository lookup with GET /repos/{owner}/{repo}/installation gives one API call, lease and token per repository. Each of those tokens covers the whole installation anyway.

Open questions

• Which account owns the prod App, and is the App installed on that account? If not, reads that name no owner have no default installation.
• Trigger checks in evals: evals use fake App credentials and cannot reach api.github.com. They need a fixed installation map, or the check must allow a save when the map cannot load.
• Search reads (/search/issues?q=repo:owner/name) could take the owner from repo:, org: or user: qualifiers. Is this worth doing now?
• Should reads with no owner use the requester's GitHub user token when one exists? A user token reaches every installation the user can access, but the read then acts as the user.

Not in scope

• The event-first trigger work in Make automation events and filters consistent and reliable #2362. Broad "all repos" triggers there will then cover every installation, so review the required repo filter rules from Make automation events and filters consistent and reliable #2362 item 7 when this lands.

Status

• feat(github): Support every GitHub App installation #2405 has steps 1 and 3 done. It also has a first version of step 2 that routes by repository: it calls GET /repos/{owner}/{repo}/installation or /orgs/{org}/installation for each target, and GET /app to find the default installation. That part must change to the owner map above.
• Step 4 is not started.

via David Cramer.

--

View Session [Sentry]