fix: add deeplinking to posthog code git setup (#1733)

## TLDR

The GitHub integration flow previously relied entirely on polling to detect when a user completed the GitHub App install in their browser. This meant the app had no reliable way to know when the flow succeeded or failed, and the UI couldn't react immediately or surface meaningful error states.

## Changes

- Added a deep link handler in `GitHubIntegrationService` that listens for `integration` callbacks from PostHog Cloud after the GitHub App install completes. The service emits typed events (`Callback`, `FlowTimedOut`) and queues callbacks that arrive before the renderer has subscribed.
- Added a 5-minute flow timeout in the service that fires `FlowTimedOut` if no deep link callback is received.
- Exposed three new tRPC endpoints: `onCallback` and `onFlowTimedOut` subscriptions, and a `consumePendingCallback` query to drain any callback that arrived before the renderer mounted.
- Added a `useGitHubIntegrationCallback` hook that subscribes to both events and drains any pending callback on mount, calling `onSuccess`, `onError`, or `onTimedOut` accordingly.
- Polling is now only used in dev mode (where the deep link protocol is not registered) and as a safety fallback timeout in production.
- The onboarding `GitIntegrationStep` now shows a timeout banner with a retry prompt, displays the connected GitHub account name when available, and surfaces a callout when GitHub is already connected on a different project.
- `GitHubIntegrationSection` in settings follows the same pattern, replacing polling-based detection with the new callback hook.
- The `next` redirect URL after GitHub authorization now points to `/account/social-connected` with query params instead of the project root, enabling the deep link callback to carry status, installation ID, and error details back to the app.

Author: k11kirky

apps/code/src/main/index.ts

@@ -13,6 +13,7 @@ import { registerMcpSandboxProtocol } from "./protocols/mcp-sandbox";
 import type { AppLifecycleService } from "./services/app-lifecycle/service";
 import type { AuthService } from "./services/auth/service";
 import type { ExternalAppsService } from "./services/external-apps/service";
+import type { GitHubIntegrationService } from "./services/github-integration/service";
 import type { NotificationService } from "./services/notification/service";
 import type { OAuthService } from "./services/oauth/service";
 import {
@@ -43,6 +44,7 @@ async function initializeServices(): Promise<void> {
   container.get<NotificationService>(MAIN_TOKENS.NotificationService);
   container.get<UpdatesService>(MAIN_TOKENS.UpdatesService);
   container.get<TaskLinkService>(MAIN_TOKENS.TaskLinkService);
+  container.get<GitHubIntegrationService>(MAIN_TOKENS.GitHubIntegrationService);
   container.get<ExternalAppsService>(MAIN_TOKENS.ExternalAppsService);
   container.get<PosthogPluginService>(MAIN_TOKENS.PosthogPluginService);
 

apps/code/src/main/services/github-integration/service.ts

@@ -1,36 +1,146 @@
+import type { IMainWindow } from "@posthog/platform/main-window";
 import type { IUrlLauncher } from "@posthog/platform/url-launcher";
 import { getCloudUrlFromRegion } from "@shared/utils/urls";
 import { inject, injectable } from "inversify";
 import { MAIN_TOKENS } from "../../di/tokens";
 import { logger } from "../../utils/logger";
+import { TypedEventEmitter } from "../../utils/typed-event-emitter";
+import type { DeepLinkService } from "../deep-link/service";
 import type { CloudRegion, StartGitHubFlowOutput } from "./schemas";
 
 const log = logger.scope("github-integration-service");
 
+const FLOW_TIMEOUT_MS = 5 * 60 * 1000;
+
+export const GitHubIntegrationEvent = {
+  Callback: "callback",
+  FlowTimedOut: "flowTimedOut",
+} as const;
+
+export interface IntegrationCallback {
+  provider: string;
+  projectId: number | null;
+  installationId: string | null;
+  status: "success" | "error";
+  errorCode: string | null;
+  errorMessage: string | null;
+}
+
+export interface FlowTimedOut {
+  projectId: number;
+}
+
+export interface GitHubIntegrationEvents {
+  [GitHubIntegrationEvent.Callback]: IntegrationCallback;
+  [GitHubIntegrationEvent.FlowTimedOut]: FlowTimedOut;
+}
+
 @injectable()
-export class GitHubIntegrationService {
+export class GitHubIntegrationService extends TypedEventEmitter<GitHubIntegrationEvents> {
+  private pendingCallback: IntegrationCallback | null = null;
+  private flowTimeout: ReturnType<typeof setTimeout> | null = null;
+
   constructor(
-    @inject(MAIN_TOKENS.UrlLauncher) private readonly urlLauncher: IUrlLauncher,
-  ) {}
+    @inject(MAIN_TOKENS.DeepLinkService)
+    private readonly deepLinkService: DeepLinkService,
+    @inject(MAIN_TOKENS.UrlLauncher)
+    private readonly urlLauncher: IUrlLauncher,
+    @inject(MAIN_TOKENS.MainWindow)
+    private readonly mainWindow: IMainWindow,
+  ) {
+    super();
+
+    this.deepLinkService.registerHandler("integration", (_path, params) =>
+      this.handleCallback(params),
+    );
+  }
 
   public async startFlow(
     region: CloudRegion,
     projectId: number,
   ): Promise<StartGitHubFlowOutput> {
     try {
       const cloudUrl = getCloudUrlFromRegion(region);
-      const next = `${cloudUrl}/project/${projectId}`;
-      const authorizeUrl = `${cloudUrl}/api/environments/${projectId}/integrations/authorize/?kind=github&next=${encodeURIComponent(next)}`;
+      const nextPath = `/account/social-connected?provider=github&project_id=${projectId}&connect_from=posthog_code`;
+      const authorizeUrl = `${cloudUrl}/api/environments/${projectId}/integrations/authorize/?kind=github&next=${encodeURIComponent(nextPath)}`;
+
+      this.clearFlowTimeout();
+      this.flowTimeout = setTimeout(() => {
+        log.warn("GitHub integration flow timed out", { projectId });
+        this.flowTimeout = null;
+        this.emit(GitHubIntegrationEvent.FlowTimedOut, { projectId });
+      }, FLOW_TIMEOUT_MS);
 
-      log.info("Opening GitHub authorization URL in browser");
       await this.urlLauncher.launch(authorizeUrl);
 
       return { success: true };
     } catch (error) {
+      this.clearFlowTimeout();
+      log.error("Failed to start GitHub integration flow", {
+        projectId,
+        error: error instanceof Error ? error.message : String(error),
+      });
       return {
         success: false,
         error: error instanceof Error ? error.message : "Unknown error",
       };
     }
   }
+
+  public consumePendingCallback(): IntegrationCallback | null {
+    const pending = this.pendingCallback;
+    this.pendingCallback = null;
+    return pending;
+  }
+
+  private handleCallback(params: URLSearchParams): boolean {
+    const projectIdRaw = params.get("project_id");
+    const parsedProjectId = projectIdRaw ? Number(projectIdRaw) : null;
+    const status = params.get("status") === "error" ? "error" : "success";
+
+    const callback: IntegrationCallback = {
+      provider: params.get("provider") ?? "",
+      projectId:
+        parsedProjectId !== null && Number.isFinite(parsedProjectId)
+          ? parsedProjectId
+          : null,
+      installationId: params.get("installation_id") || null,
+      status,
+      errorCode: params.get("error_code") || null,
+      errorMessage: params.get("error_message") || null,
+    };
+
+    this.clearFlowTimeout();
+
+    if (status === "error") {
+      log.error("Received integration callback with error", {
+        provider: callback.provider,
+        projectId: callback.projectId,
+        errorCode: callback.errorCode,
+        errorMessage: callback.errorMessage,
+      });
+    }
+
+    const hasListeners =
+      this.listenerCount(GitHubIntegrationEvent.Callback) > 0;
+    if (hasListeners) {
+      this.emit(GitHubIntegrationEvent.Callback, callback);
+    } else {
+      this.pendingCallback = callback;
+    }
+
+    if (this.mainWindow.isMinimized()) {
+      this.mainWindow.restore();
+    }
+    this.mainWindow.focus();
+
+    return true;
+  }
+
+  private clearFlowTimeout(): void {
+    if (this.flowTimeout) {
+      clearTimeout(this.flowTimeout);
+      this.flowTimeout = null;
+    }
+  }
 }

apps/code/src/main/trpc/routers/github-integration.ts

@@ -4,7 +4,12 @@ import {
   startGitHubFlowInput,
   startGitHubFlowOutput,
 } from "../../services/github-integration/schemas";
-import type { GitHubIntegrationService } from "../../services/github-integration/service";
+import {
+  type FlowTimedOut,
+  GitHubIntegrationEvent,
+  type GitHubIntegrationService,
+  type IntegrationCallback,
+} from "../../services/github-integration/service";
 import { publicProcedure, router } from "../trpc";
 
 const getService = () =>
@@ -17,4 +22,40 @@ export const githubIntegrationRouter = router({
     .mutation(({ input }) =>
       getService().startFlow(input.region, input.projectId),
     ),
+
+  /**
+   * Subscribe to GitHub integration deep link callbacks emitted after the user
+   * completes (or errors out of) the GitHub App install flow on PostHog Cloud.
+   */
+  onCallback: publicProcedure.subscription(async function* (opts) {
+    const service = getService();
+    const iterable = service.toIterable(GitHubIntegrationEvent.Callback, {
+      signal: opts.signal,
+    });
+    for await (const data of iterable) {
+      yield data;
+    }
+  }),
+
+  /**
+   * Subscribe to flow timeout events (5 minutes with no deep link callback).
+   */
+  onFlowTimedOut: publicProcedure.subscription(async function* (opts) {
+    const service = getService();
+    const iterable = service.toIterable(GitHubIntegrationEvent.FlowTimedOut, {
+      signal: opts.signal,
+    });
+    for await (const data of iterable) {
+      yield data;
+    }
+  }),
+
+  /**
+   * Get any integration callback that arrived before the renderer subscribed.
+   */
+  consumePendingCallback: publicProcedure.query(
+    (): IntegrationCallback | null => getService().consumePendingCallback(),
+  ),
 });
+
+export type { IntegrationCallback, FlowTimedOut };

apps/code/src/renderer/features/integrations/hooks/useGitHubIntegrationCallback.ts

@@ -0,0 +1,75 @@
+import { trpcClient, useTRPC } from "@renderer/trpc/client";
+import { useSubscription } from "@trpc/tanstack-react-query";
+import { logger } from "@utils/logger";
+import { useEffect, useRef } from "react";
+
+const log = logger.scope("github-integration-callback-hook");
+
+const DEFAULT_ERROR_MESSAGE =
+  "GitHub install failed. Please try connecting again.";
+
+interface Options {
+  onSuccess: (projectId: number | null) => void;
+  onError: (message: string) => void;
+  onTimedOut?: () => void;
+}
+
+/**
+ * Subscribes to GitHub integration deep link callbacks and drains any pending
+ * callback that arrived before the subscription was established (cold-start).
+ */
+export function useGitHubIntegrationCallback({
+  onSuccess,
+  onError,
+  onTimedOut,
+}: Options): void {
+  const trpcReact = useTRPC();
+  const hasConsumedPendingRef = useRef(false);
+
+  const optsRef = useRef({ onSuccess, onError, onTimedOut });
+  optsRef.current = { onSuccess, onError, onTimedOut };
+
+  useSubscription(
+    trpcReact.githubIntegration.onCallback.subscriptionOptions(undefined, {
+      onData: (data) => {
+        log.info("Received integration deep link callback", data);
+        if (data.status === "error") {
+          optsRef.current.onError(data.errorMessage ?? DEFAULT_ERROR_MESSAGE);
+          return;
+        }
+        optsRef.current.onSuccess(data.projectId);
+      },
+    }),
+  );
+
+  useSubscription(
+    trpcReact.githubIntegration.onFlowTimedOut.subscriptionOptions(undefined, {
+      onData: (data) => {
+        log.info("GitHub integration flow timed out", data);
+        optsRef.current.onTimedOut?.();
+      },
+    }),
+  );
+
+  useEffect(() => {
+    if (hasConsumedPendingRef.current) return;
+    hasConsumedPendingRef.current = true;
+    void (async () => {
+      try {
+        const pending =
+          await trpcClient.githubIntegration.consumePendingCallback.query();
+        if (!pending) return;
+        log.info("Consumed pending integration callback on mount", pending);
+        if (pending.status === "error") {
+          optsRef.current.onError(
+            pending.errorMessage ?? DEFAULT_ERROR_MESSAGE,
+          );
+          return;
+        }
+        optsRef.current.onSuccess(pending.projectId);
+      } catch (error) {
+        log.error("Failed to consume pending integration callback", error);
+      }
+    })();
+  }, []);
+}

apps/code/src/renderer/features/integrations/stores/integrationStore.ts

@@ -1,8 +1,20 @@
 import { create } from "zustand";
 
+export interface IntegrationAccount {
+  name?: string;
+  type?: string;
+}
+
+export interface IntegrationConfig {
+  account?: IntegrationAccount;
+  [key: string]: unknown;
+}
+
 export interface Integration {
   id: number;
   kind: string;
+  config?: IntegrationConfig;
+  display_name?: string;
   [key: string]: unknown;
 }