@playrunner/github 0.1.0

package/LICENSE

@@ -0,0 +1,134 @@
+Playrunner Sustainable Use License v1.0
+
+Copyright (c) 2026 Concept AI PTY LTD
+
+This Playrunner Sustainable Use License v1.0 (the "License") applies to the
+source code and related repository materials for Playrunner that are owned by
+Concept AI PTY LTD, unless a file or directory states a different license.
+
+1. Definitions
+
+"Licensor" means Concept AI PTY LTD.
+
+"Licensed Work" means the Playrunner source code and related repository
+materials made available by Licensor under this License, excluding any material
+that is expressly made available under a different license or other third-party
+terms.
+
+"You" means the individual or legal entity exercising rights under this
+License.
+
+"Internal Business Purposes" means use solely to support Your own internal
+operations. It does not include making the Licensed Work, or a material part of
+its functionality, available to third parties as a product or service.
+
+2. License Grant
+
+Subject to this License, Licensor grants You a worldwide, non-exclusive,
+royalty-free, non-transferable, non-sublicensable license to use,
+copy, run, modify, create derivative works of, and distribute the Licensed
+Work.
+
+3. Permitted Uses
+
+You may exercise the rights granted in Section 2 only for:
+
+a. Your Internal Business Purposes; or
+b. personal, educational, evaluation, or other non-commercial purposes.
+
+For clarity, use by Your employees, contractors, and controlled affiliates on
+Your behalf for Your Internal Business Purposes is permitted under this
+License.
+
+4. Redistribution Conditions
+
+If You distribute the Licensed Work or a modified version, You must:
+
+a. include a copy of this License;
+b. preserve all copyright, attribution, and license notices;
+c. clearly identify that You changed the Licensed Work; and
+d. distribute it only free of charge and only for uses otherwise permitted by
+   Section 3.
+
+5. Prohibited Uses
+
+Unless Licensor gives You separate written permission, You may not:
+
+a. sell, license, sublicense, rent, lease, or otherwise monetize the Licensed
+   Work or access to it;
+b. provide the Licensed Work, or a service substantially based on it, to third
+   parties on a hosted, managed, white-label, or software-as-a-service basis;
+c. embed, bundle, or integrate the Licensed Work into a commercial product or
+   service where a material part of the value delivered to third parties comes
+   from the Licensed Work or its functionality, except where the Licensed Work
+   is used only as an internal tool supporting Your own operations;
+d. remove, obscure, or alter any ownership, attribution, or license notices; or
+e. use Licensor's names, logos, or trademarks except for reasonable nominative
+   reference or as separately authorized in writing.
+
+6. Patent License
+
+Subject to this License, Licensor grants You a worldwide, non-exclusive,
+royalty-free patent license under patent claims that Licensor can license and
+that are necessarily infringed by the unmodified Licensed Work, solely to make,
+use, run, and import the Licensed Work for the permitted uses in this License.
+
+This patent license does not apply to:
+
+a. Your modifications to the Licensed Work;
+b. combinations of the Licensed Work with other software, products, or services
+   unless such combination is part of the unmodified Licensed Work as released
+   by Licensor; or
+c. any activity that is prohibited by this License.
+
+If You bring or assist in bringing a patent claim against Licensor or any
+recipient of the Licensed Work alleging that the Licensed Work infringes a
+patent, Your rights under this License terminate immediately.
+
+7. Contributions
+
+Unless Licensor agrees otherwise in writing, any contribution intentionally
+submitted by You for inclusion in the Licensed Work is provided under this
+License, and You represent that You have the right to submit it on those terms.
+
+8. Third-Party Materials
+
+The Licensed Work may include or depend on third-party software or other
+materials that are licensed under separate terms. Those third-party components
+remain subject to their own licenses, notices, and obligations.
+
+9. Termination
+
+If You violate this License, Your rights under it terminate automatically.
+Licensor may reinstate those rights if You fully cure the violation within 30
+days after receiving written notice from Licensor. Termination does not limit
+any other remedies available to Licensor.
+
+10. No Warranty
+
+TO THE MAXIMUM EXTENT PERMITTED BY APPLICABLE LAW, THE LICENSED WORK IS
+PROVIDED "AS IS" AND "AS AVAILABLE", WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, WHETHER EXPRESS, IMPLIED, STATUTORY, OR OTHERWISE, INCLUDING ANY IMPLIED
+WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, TITLE, AND
+NON-INFRINGEMENT.
+
+11. Limitation of Liability
+
+TO THE MAXIMUM EXTENT PERMITTED BY APPLICABLE LAW, IN NO EVENT WILL LICENSOR OR
+ITS AFFILIATES, DIRECTORS, OFFICERS, EMPLOYEES, OR CONTRIBUTORS BE LIABLE FOR
+ANY INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, PUNITIVE, OR CONSEQUENTIAL
+DAMAGES, OR FOR ANY LOSS OF DATA, PROFITS, REVENUE, GOODWILL, OR BUSINESS
+INTERRUPTION, ARISING OUT OF OR RELATING TO THIS LICENSE OR THE LICENSED WORK,
+EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
+
+TO THE MAXIMUM EXTENT PERMITTED BY APPLICABLE LAW, LICENSOR'S TOTAL LIABILITY
+ARISING OUT OF OR RELATING TO THIS LICENSE OR THE LICENSED WORK WILL NOT EXCEED
+ONE HUNDRED AUSTRALIAN DOLLARS (AUD $100).
+
+12. General
+
+This License is the complete agreement between You and Licensor regarding the
+Licensed Work. If any provision of this License is held unenforceable, the
+remaining provisions will remain in effect to the fullest extent permitted by
+law. A waiver of any breach or default under this License is effective only if
+made in writing by Licensor.

package/README.md

@@ -0,0 +1,30 @@
+# @playrunner/github
+
+GitHub authentication and repository access for Playrunner workflows.
+
+## Install
+
+```bash
+npm install @playrunner/github
+```
+
+Add the package as a direct production dependency of the Playrunner frontend and API. Playwright installations also use this package for repository authentication.
+
+## Package surfaces
+
+- `@playrunner/github` exports the GitHub integration, icon, and settings UI.
+- `@playrunner/github/api` exports token exchange and refresh API routes.
+- `@playrunner/github/assets/github.svg` exports the package-owned icon.
+
+```ts
+import githubIntegration, { GithubSettingsModal } from '@playrunner/github';
+import githubApiContribution from '@playrunner/github/api';
+```
+
+## Documentation
+
+See the [GitHub integration documentation](https://playrunner.dev/docs/integration-packages/github/) for GitHub App setup, exports, and Playrunner build integration.
+
+## License
+
+Licensed under the [Playrunner Sustainable Use License](https://github.com/playrunner/playrunner/blob/main/LICENSE).

package/assets/github.svg

@@ -0,0 +1,5 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="currentColor" aria-hidden="true">
+  <title>GitHub</title>
+  <path d="M12,2A10,10 0 0,0 2,12c0 4.42 2.87 8.17 6.84 9.49.5.09.68-.22.68-.49 0-.24-.01-.87-.01-1.71-2.78.62-3.37-1.23-3.37-1.23-.45-1.18-1.11-1.49-1.11-1.49-.91-.63.07-.62.07-.62 1 .07 1.53 1.07 1.53 1.07.9 1.56 2.36 1.11 2.94.85.09-.66.35-1.11.63-1.37-2.22-.26-4.55-1.14-4.55-5.07 0-1.12.39-2.03 1.03-2.75-.1-.26-.45-1.31.1-2.73 0 0 .84-.27 2.75 1.05a9.38 9.38 0 0 1 5 0c1.91-1.32 2.75-1.05 2.75-1.05.55 1.42.2 2.47.1 2.73.64.72 1.03 1.63 1.03 2.75 0 3.94-2.34 4.81-4.57 5.06.36.31.68.92.68 1.86 0 1.34-.01 2.41-.01 2.74 0 .27.18.59.69.49C19.14 20.41 22 16.66 22 12.24A10.24 10.24 0 0 0 12,2z"/>
+</svg>
+

package/package.json

@@ -0,0 +1,101 @@
+{
+  "name": "@playrunner/github",
+  "version": "0.1.0",
+  "description": "GitHub integration package for Playrunner.",
+  "keywords": [
+    "playrunner",
+    "github",
+    "integration"
+  ],
+  "license": "SEE LICENSE IN LICENSE",
+  "author": "Concept AI PTY LTD",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/playrunner/playrunner.git",
+    "directory": "packages/github"
+  },
+  "homepage": "https://playrunner.dev/docs/integration-packages/github/",
+  "bugs": {
+    "url": "https://github.com/playrunner/playrunner/issues"
+  },
+  "type": "module",
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org",
+    "access": "public"
+  },
+  "playrunner": {
+    "integration": {
+      "id": "github",
+      "frontend": ".",
+      "api": "./api"
+    }
+  },
+  "exports": {
+    ".": {
+      "types": "./src/frontend/index.tsx",
+      "import": "./src/frontend/index.tsx",
+      "require": "./src/frontend/index.tsx",
+      "default": "./src/frontend/index.tsx"
+    },
+    "./frontend": {
+      "types": "./src/frontend/index.tsx",
+      "import": "./src/frontend/index.tsx",
+      "require": "./src/frontend/index.tsx",
+      "default": "./src/frontend/index.tsx"
+    },
+    "./api": {
+      "types": "./src/api/index.ts",
+      "import": "./src/api/index.ts",
+      "require": "./src/api/index.ts",
+      "default": "./src/api/index.ts"
+    },
+    "./assets/github.svg": "./assets/github.svg"
+  },
+  "files": [
+    "LICENSE",
+    "README.md",
+    "assets",
+    "src"
+  ],
+  "scripts": {
+    "lint": "eslint .",
+    "lint:fix": "eslint . --fix",
+    "format": "prettier --write .",
+    "format:check": "prettier --check .",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "express": "^5.2.1"
+  },
+  "peerDependencies": {
+    "@playrunner/integration-sdk": "^0.1.0",
+    "lucide-react": "^0.546.0",
+    "react": "^19.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@playrunner/integration-sdk": {
+      "optional": true
+    },
+    "lucide-react": {
+      "optional": true
+    },
+    "react": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.39.4",
+    "@types/express": "^5.0.6",
+    "@types/react": "^19.2.14",
+    "eslint": "^9.39.4",
+    "eslint-config-prettier": "10.1.8",
+    "eslint-plugin-react": "^7.37.5",
+    "eslint-plugin-react-hooks": "^7.1.1",
+    "eslint-plugin-react-refresh": "^0.5.3",
+    "globals": "^17.6.0",
+    "lucide-react": "^0.546.0",
+    "prettier": "3.8.4",
+    "typescript": "~5.8.2",
+    "typescript-eslint": "^8.61.1"
+  }
+}

package/src/api/index.ts

@@ -0,0 +1,80 @@
+import { Router } from 'express';
+
+export const githubRouter = Router();
+
+export const githubApiContribution = {
+  id: 'github',
+  mountPath: '/api/github',
+  router: githubRouter,
+};
+
+export default githubApiContribution;
+
+// Proxy endpoint to exchange GitHub OAuth code for an access token to bypass CORS
+githubRouter.post('/token', async (req, res) => {
+  const { code, client_id, client_secret } = req.body;
+
+  try {
+    const gRes = await fetch('https://github.com/login/oauth/access_token', {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        Accept: 'application/json',
+        'User-Agent': 'Playrunner-App',
+      },
+      body: JSON.stringify({
+        client_id,
+        client_secret,
+        code,
+      }),
+    });
+
+    const text = await gRes.text();
+    try {
+      const data = JSON.parse(text);
+      res.json(data);
+    } catch {
+      console.error('Token exchange failed. GitHub returned non-JSON:', text);
+      res
+        .status(500)
+        .json({ error: 'Failed to exchange token', details: text });
+    }
+  } catch (err) {
+    console.error('Token exchange error:', err);
+    res.status(500).json({ error: 'Failed to exchange token' });
+  }
+});
+
+// Proxy endpoint to refresh GitHub OAuth token
+githubRouter.post('/refresh', async (req, res) => {
+  const { refresh_token, client_id, client_secret } = req.body;
+
+  try {
+    const gRes = await fetch('https://github.com/login/oauth/access_token', {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        Accept: 'application/json',
+        'User-Agent': 'Playrunner-App',
+      },
+      body: JSON.stringify({
+        client_id,
+        client_secret,
+        refresh_token,
+        grant_type: 'refresh_token',
+      }),
+    });
+
+    const text = await gRes.text();
+    try {
+      const data = JSON.parse(text);
+      res.json(data);
+    } catch {
+      console.error('Token refresh failed. GitHub returned non-JSON:', text);
+      res.status(500).json({ error: 'Failed to refresh token', details: text });
+    }
+  } catch (err) {
+    console.error('Token refresh error:', err);
+    res.status(500).json({ error: 'Failed to refresh token' });
+  }
+});

package/src/frontend/GithubIcon.tsx

@@ -0,0 +1,13 @@
+export function GithubIcon({ className }: { className?: string }) {
+  return (
+    <svg
+      xmlns="http://www.w3.org/2000/svg"
+      viewBox="0 0 24 24"
+      fill="currentColor"
+      aria-hidden="true"
+      className={className}
+    >
+      <path d="M12,2A10,10 0 0,0 2,12c0 4.42 2.87 8.17 6.84 9.49.5.09.68-.22.68-.49 0-.24-.01-.87-.01-1.71-2.78.62-3.37-1.23-3.37-1.23-.45-1.18-1.11-1.49-1.11-1.49-.91-.63.07-.62.07-.62 1 .07 1.53 1.07 1.53 1.07.9 1.56 2.36 1.11 2.94.85.09-.66.35-1.11.63-1.37-2.22-.26-4.55-1.14-4.55-5.07 0-1.12.39-2.03 1.03-2.75-.1-.26-.45-1.31.1-2.73 0 0 .84-.27 2.75 1.05a9.38 9.38 0 0 1 5 0c1.91-1.32 2.75-1.05 2.75-1.05.55 1.42.2 2.47.1 2.73.64.72 1.03 1.63 1.03 2.75 0 3.94-2.34 4.81-4.57 5.06.36.31.68.92.68 1.86 0 1.34-.01 2.41-.01 2.74 0 .27.18.59.69.49C19.14 20.41 22 16.66 22 12.24A10.24 10.24 0 0 0 12,2z" />
+    </svg>
+  );
+}

package/src/frontend/GithubSettingsModal.tsx

@@ -0,0 +1,475 @@
+import React, { useState } from 'react';
+import {
+  BookOpen,
+  Check,
+  ChevronRight,
+  Copy,
+  ExternalLink,
+  Loader2,
+} from 'lucide-react';
+import {
+  IntegrationConnectionAutofillGuard,
+  IntegrationConnectionInput,
+  useIntegrationHost,
+} from '@playrunner/integration-sdk';
+import { GithubIcon } from './GithubIcon';
+
+interface GithubSettingsModalProps {
+  isOpen: boolean;
+  onClose: () => void;
+}
+
+const DEFAULT_DOCS_URL = 'https://playrunner.dev';
+const GITHUB_SETUP_DOCS_URL = getDocsUrl('docs/tutorials/connect-github');
+
+type DocsImportMeta = ImportMeta & {
+  env?: {
+    VITE_DOCS_URL?: string;
+  };
+};
+
+function getDocsUrl(path = '') {
+  const baseUrl = (
+    (import.meta as DocsImportMeta).env?.VITE_DOCS_URL || DEFAULT_DOCS_URL
+  )
+    .trim()
+    .replace(/\/+$/, '');
+  const normalizedPath = path.trim().replace(/^\/+/, '');
+
+  return normalizedPath ? `${baseUrl}/${normalizedPath}` : baseUrl;
+}
+
+export function GithubSettingsModal({
+  isOpen,
+  onClose,
+}: GithubSettingsModalProps) {
+  const { auth, store, ui } = useIntegrationHost();
+  const Modal = ui.Modal;
+  const [githubAppName, setGithubAppName] = useState('');
+  const [githubClientId, setGithubClientId] = useState('');
+  const [githubClientSecret, setGithubClientSecret] = useState('');
+  const [githubAppSlug, setGithubAppSlug] = useState<string | null>(null);
+  const [isAuthenticating, setIsAuthenticating] = useState(false);
+  const [authSuccess, setAuthSuccess] = useState(false);
+  const [copiedUrl, setCopiedUrl] = useState(false);
+  const popupRef = React.useRef<Window | null>(null);
+
+  const callbackUrl = `${window.location.origin}/oauth/callback/github`;
+
+  const handleCopyUrl = () => {
+    navigator.clipboard.writeText(callbackUrl);
+    setCopiedUrl(true);
+    setTimeout(() => setCopiedUrl(false), 2000);
+  };
+
+  React.useEffect(() => {
+    let isMounted = true;
+    const fetchCredentials = async () => {
+      if (isOpen && auth.currentUser) {
+        try {
+          const data = await store.getIntegration(
+            auth.currentUser.uid,
+            'github',
+          );
+          if (data && isMounted) {
+            if (data.clientId && data.accessToken) {
+              setGithubAppName(data.appName || data.appSlug || '');
+              setGithubClientId(data.clientId);
+              setGithubClientSecret(data.clientSecret || '');
+              if (data.appSlug) setGithubAppSlug(data.appSlug);
+              setAuthSuccess(true);
+            } else if (data.clientId) {
+              setGithubAppName(data.appName || data.appSlug || '');
+              setGithubClientId(data.clientId);
+              setGithubClientSecret(data.clientSecret || '');
+              if (data.appSlug) setGithubAppSlug(data.appSlug);
+            }
+          }
+        } catch (error) {
+          console.error('Failed to fetch Github credentials', error);
+        }
+      }
+    };
+
+    if (isOpen) {
+      fetchCredentials();
+    } else {
+      setAuthSuccess(false);
+      setIsAuthenticating(false);
+      setGithubAppName('');
+      setGithubClientId('');
+      setGithubClientSecret('');
+      setGithubAppSlug(null);
+    }
+
+    return () => {
+      isMounted = false;
+    };
+  }, [auth, isOpen, store]);
+
+  const handleAuthenticateGithub = async () => {
+    try {
+      setIsAuthenticating(true);
+
+      const currentUser = auth.currentUser;
+
+      if (currentUser) {
+        await store.saveIntegration(currentUser.uid, 'github', {
+          appName: githubAppName,
+          clientId: githubClientId,
+          clientSecret: githubClientSecret,
+          updatedAt: new Date().toISOString(),
+        });
+      }
+
+      let isProcessing = false;
+      const messageListener = async (event: MessageEvent) => {
+        if (event.origin !== window.location.origin) return;
+        if (event.data?.type === 'oauth_callback' && event.data?.success) {
+          if (isProcessing) return;
+          isProcessing = true;
+
+          if (auth.currentUser) {
+            if (event.data?.params?.code) {
+              try {
+                // Exchange the code for an access token
+                const token = await auth.currentUser.getIdToken();
+                const tokenRes = await fetch('/api/github/token', {
+                  method: 'POST',
+                  headers: {
+                    'Content-Type': 'application/json',
+                    Authorization: `Bearer ${token}`,
+                  },
+                  body: JSON.stringify({
+                    code: event.data.params.code,
+                    client_id: githubClientId,
+                    client_secret: githubClientSecret,
+                  }),
+                });
+
+                const tokenData = await tokenRes.json();
+
+                if (!tokenData.access_token) {
+                  throw new Error(
+                    `Failed to retrieve access token: ${JSON.stringify(tokenData)}`,
+                  );
+                }
+
+                const integrationData: any = {
+                  appName: githubAppName,
+                  clientId: githubClientId,
+                  clientSecret: githubClientSecret,
+                  code: event.data.params.code,
+                  accessToken: tokenData.access_token,
+                  refreshToken: tokenData.refresh_token,
+                  expiresAt: tokenData.expires_in
+                    ? Date.now() + tokenData.expires_in * 1000
+                    : undefined,
+                  refreshTokenExpiresAt: tokenData.refresh_token_expires_in
+                    ? Date.now() + tokenData.refresh_token_expires_in * 1000
+                    : undefined,
+                  appSlug: githubAppName,
+                  updatedAt: new Date().toISOString(),
+                };
+
+                // Store installation_id if it was provided
+                if (event.data.params.installation_id) {
+                  integrationData.installationId =
+                    event.data.params.installation_id;
+                }
+
+                await store.saveIntegration(
+                  auth.currentUser.uid,
+                  'github',
+                  integrationData,
+                );
+
+                setGithubAppSlug(githubAppName);
+                if (popupRef.current)
+                  popupRef.current.postMessage(
+                    { type: 'oauth_close' },
+                    window.location.origin,
+                  );
+              } catch (err) {
+                console.error('Failed to save auth code:', err);
+                if (popupRef.current)
+                  popupRef.current.postMessage(
+                    { type: 'oauth_close' },
+                    window.location.origin,
+                  );
+              }
+            } else if (event.data?.params?.installation_id) {
+              if (event.data?.params?.setup_action === 'update') {
+                // Just an update to the installation (e.g. adding repositories)
+                if (popupRef.current)
+                  popupRef.current.postMessage(
+                    { type: 'oauth_close' },
+                    window.location.origin,
+                  );
+              } else {
+                // If there is an installation ID but no code, they probably forgot to check "Request user authorization (OAuth) during installation"
+                alert(
+                  "Installation successful, but no OAuth code found. Please ensure you checked 'Request user authorization (OAuth) during installation' in your GitHub App settings.",
+                );
+                if (popupRef.current)
+                  popupRef.current.postMessage(
+                    { type: 'oauth_close' },
+                    window.location.origin,
+                  );
+              }
+            }
+          }
+
+          setIsAuthenticating(false);
+          setAuthSuccess(true);
+          window.removeEventListener('message', messageListener);
+        }
+      };
+
+      window.addEventListener('message', messageListener);
+
+      const authUrl = `https://github.com/apps/${githubAppName}/installations/new`;
+
+      const width = 800;
+      const height = 700;
+      const left = window.screen.width / 2 - width / 2;
+      const top = window.screen.height / 2 - height / 2;
+      popupRef.current = window.open(
+        authUrl,
+        'GithubOAuth',
+        `toolbar=no, location=no, directories=no, status=no, menubar=no, scrollbars=no, resizable=no, copyhistory=no, width=${width}, height=${height}, top=${top}, left=${left}`,
+      );
+
+      const checkPopup = setInterval(() => {
+        if (!popupRef.current || popupRef.current.closed) {
+          clearInterval(checkPopup);
+          setIsAuthenticating(false);
+          window.removeEventListener('message', messageListener);
+        }
+      }, 500);
+    } catch (error) {
+      console.error('Failed to save credentials', error);
+      setIsAuthenticating(false);
+    }
+  };
+
+  const handleDisconnect = async () => {
+    if (!auth.currentUser) return;
+    try {
+      await store.deleteIntegration(auth.currentUser.uid, 'github');
+      setAuthSuccess(false);
+      setGithubAppName('');
+      setGithubClientId('');
+      setGithubClientSecret('');
+      setGithubAppSlug(null);
+    } catch (error) {
+      console.error('Failed to disconnect Github', error);
+    }
+  };
+
+  return (
+    <Modal
+      isOpen={isOpen}
+      onClose={onClose}
+      zIndex={70}
+      title="Connect to GitHub"
+      icon={<GithubIcon className="w-5 h-5 text-[var(--foreground)]" />}
+      footer={
+        !authSuccess ? (
+          <button
+            onClick={handleAuthenticateGithub}
+            disabled={
+              !githubAppName ||
+              !githubClientId ||
+              !githubClientSecret ||
+              isAuthenticating
+            }
+            className="flex items-center gap-2 px-4 py-2 rounded-lg bg-[var(--accent)] hover:bg-[var(--accent)]/90 text-[var(--accent-foreground)] font-medium text-sm transition-colors shadow-sm disabled:opacity-50 disabled:cursor-not-allowed"
+          >
+            {isAuthenticating ? (
+              <>
+                <Loader2 className="w-4 h-4 animate-spin" />
+                Authenticating...
+              </>
+            ) : (
+              <>
+                Authenticate
+                <ChevronRight className="w-4 h-4" />
+              </>
+            )}
+          </button>
+        ) : null
+      }
+    >
+      {authSuccess ? (
+        <div className="flex flex-col items-center justify-center text-center gap-4 py-8">
+          <div className="w-16 h-16 rounded-full bg-green-500/20 flex items-center justify-center animate-in zoom-in duration-300">
+            <Check className="w-8 h-8 text-green-500" />
+          </div>
+          <div>
+            <h3 className="text-xl font-semibold text-[var(--foreground)] mb-2">
+              GitHub Connected Successfully
+            </h3>
+            <p className="text-muted text-sm max-w-[320px] mx-auto mb-4">
+              Your GitHub App is connected. You can now use it to manage your
+              repositories.
+            </p>
+
+            <div className="bg-[var(--control-bg)] border border-[var(--border)] rounded-lg p-4 text-left max-w-sm mx-auto mb-6">
+              <h4 className="text-sm font-medium text-[var(--foreground)] mb-2">
+                Manage Repositories
+              </h4>
+
+              <div className="space-y-3 text-xs text-muted">
+                <p>
+                  You can change which repositories the app has access to at any
+                  time.
+                </p>
+                {githubAppSlug && (
+                  <a
+                    href={`https://github.com/apps/${githubAppSlug}/installations/new`}
+                    target="_blank"
+                    rel="noopener noreferrer"
+                    className="flex justify-center items-center gap-2 px-3 py-2 mt-2 w-full rounded-md bg-[var(--foreground)] text-[var(--background)] hover:bg-[var(--foreground)]/90 font-medium transition-colors"
+                  >
+                    Configure App Repositories
+                  </a>
+                )}
+              </div>
+            </div>
+
+            <div className="flex items-center justify-center gap-4">
+              <button
+                onClick={() => setAuthSuccess(false)}
+                className="text-xs text-muted hover:text-[var(--foreground)] underline transition-colors"
+              >
+                Change Credentials
+              </button>
+              <span className="text-muted text-xs">/</span>
+              <button
+                onClick={handleDisconnect}
+                className="text-xs text-red-500 hover:text-red-400 underline transition-colors"
+              >
+                Disconnect
+              </button>
+            </div>
+          </div>
+          <button
+            onClick={onClose}
+            className="mt-4 flex items-center gap-2 px-4 py-2 rounded-lg bg-surface border border-subtle hover:bg-surface-hover text-[var(--foreground)] font-medium text-sm transition-colors shadow-sm"
+          >
+            Close Menu
+          </button>
+        </div>
+      ) : (
+        <div className="flex flex-col gap-6">
+          <IntegrationConnectionAutofillGuard connectionId="github" />
+
+          <div className="rounded-xl border border-[var(--border)] bg-[var(--surface-hover)] p-4 text-left">
+            <div className="flex items-start gap-3">
+              <div className="flex h-8 w-8 shrink-0 items-center justify-center rounded-lg border border-[var(--border)] bg-[var(--background)]">
+                <BookOpen className="h-4 w-4 text-muted" />
+              </div>
+              <div className="min-w-0 flex-1">
+                <p className="text-sm font-medium text-[var(--foreground)]">
+                  GitHub App setup
+                </p>
+                <p className="mt-1 text-xs leading-relaxed text-muted">
+                  Use the setup guide to create the GitHub App, configure
+                  repository permissions, and find the app slug, client ID, and
+                  client secret.
+                </p>
+                <a
+                  href={GITHUB_SETUP_DOCS_URL}
+                  target="_blank"
+                  rel="noopener noreferrer"
+                  className="mt-3 inline-flex items-center gap-1.5 text-xs font-medium text-[var(--foreground)] underline underline-offset-4 hover:text-muted"
+                >
+                  Open GitHub setup guide
+                  <ExternalLink className="h-3.5 w-3.5" />
+                </a>
+              </div>
+            </div>
+          </div>
+
+          <div className="space-y-2">
+            <p className="text-xs font-medium text-muted">Callback URL</p>
+            <p className="text-xs leading-relaxed text-muted">
+              Use this value when the setup guide asks for the callback URL and
+              setup URL.
+            </p>
+            <div className="relative">
+              <code className="block p-3 pr-10 bg-[var(--background)] border border-subtle rounded text-xs select-all font-mono text-blue-400 overflow-x-auto whitespace-nowrap">
+                {callbackUrl}
+              </code>
+              <button
+                type="button"
+                onClick={handleCopyUrl}
+                className="absolute top-2 right-2 p-1 rounded bg-[var(--background)] text-muted hover:text-[var(--foreground)] hover:bg-surface-hover transition-colors"
+                title="Copy URL"
+              >
+                {copiedUrl ? (
+                  <Check className="w-3.5 h-3.5 text-green-500" />
+                ) : (
+                  <Copy className="w-3.5 h-3.5" />
+                )}
+              </button>
+            </div>
+          </div>
+
+          <div className="space-y-4 pt-2 border-t border-subtle">
+            <div>
+              <label
+                htmlFor="github-connection-field-a"
+                className="block text-xs font-medium text-muted mb-1.5"
+              >
+                GitHub App Name (URL Slug)
+              </label>
+              <IntegrationConnectionInput
+                id="github-connection-field-a"
+                connectionId="github"
+                fieldSlot="a"
+                placeholder="e.g. my-awesome-app"
+                value={githubAppName}
+                onChange={(e) => setGithubAppName(e.target.value)}
+              />
+            </div>
+            <div>
+              <label
+                htmlFor="github-connection-field-b"
+                className="block text-xs font-medium text-muted mb-1.5"
+              >
+                Client ID
+              </label>
+              <IntegrationConnectionInput
+                id="github-connection-field-b"
+                connectionId="github"
+                fieldSlot="b"
+                placeholder="Paste value from GitHub app"
+                value={githubClientId}
+                onChange={(e) => setGithubClientId(e.target.value)}
+              />
+            </div>
+            <div>
+              <label
+                htmlFor="github-connection-field-c"
+                className="block text-xs font-medium text-muted mb-1.5"
+              >
+                Client Secret
+              </label>
+              <IntegrationConnectionInput
+                id="github-connection-field-c"
+                connectionId="github"
+                fieldSlot="c"
+                mode="secret"
+                placeholder="Paste value from GitHub app"
+                value={githubClientSecret}
+                onChange={(e) => setGithubClientSecret(e.target.value)}
+              />
+            </div>
+          </div>
+        </div>
+      )}
+    </Modal>
+  );
+}

package/src/frontend/icon.ts

@@ -0,0 +1,2 @@
+export const githubIconUrl = new URL('../../assets/github.svg', import.meta.url)
+  .href;

package/src/frontend/index.tsx

@@ -0,0 +1,23 @@
+import type { Integration } from '@playrunner/integration-sdk';
+import { GithubSettingsModal } from './GithubSettingsModal';
+import { GithubIcon } from './GithubIcon';
+import { refreshGithubTokenIfNeeded } from './tokenRefresh';
+
+export const githubIntegration: Integration = {
+  id: 'github',
+  name: 'GitHub',
+  category: 'Version Control',
+  description: 'Sync repositories and trigger actions',
+  icon: GithubIcon,
+  nodeType: 'trigger',
+  iconRenderMode: 'mask',
+  getAuthPath: (uid) => `users/${uid}/integrations/github`,
+  SettingsModal: GithubSettingsModal,
+  refreshStoredIntegration: refreshGithubTokenIfNeeded,
+};
+
+export default githubIntegration;
+
+export { GithubIcon } from './GithubIcon';
+export { GithubSettingsModal } from './GithubSettingsModal';
+export { githubIconUrl } from './icon';

package/src/frontend/tokenRefresh.ts

@@ -0,0 +1,79 @@
+import type { IntegrationRefreshContext } from '@playrunner/integration-sdk';
+
+function isBadGithubRefreshTokenError(tokenData: any) {
+  return tokenData?.error === 'bad_refresh_token';
+}
+
+export async function refreshGithubTokenIfNeeded({
+  integrationData,
+  getApiHeaders,
+  saveIntegration,
+  deleteIntegration,
+}: IntegrationRefreshContext) {
+  if (
+    !integrationData ||
+    !integrationData.accessToken ||
+    !integrationData.refreshToken ||
+    !integrationData.expiresAt
+  ) {
+    return integrationData;
+  }
+
+  if (Date.now() + 5 * 60 * 1000 <= integrationData.expiresAt) {
+    return integrationData;
+  }
+
+  try {
+    console.log('GitHub token is expired or expiring soon, refreshing...');
+    const res = await fetch('/api/github/refresh', {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        ...(await getApiHeaders()),
+      },
+      body: JSON.stringify({
+        refresh_token: integrationData.refreshToken,
+        client_id: integrationData.clientId,
+        client_secret: integrationData.clientSecret,
+      }),
+    });
+
+    const tokenData = await res.json();
+
+    if (tokenData.access_token) {
+      integrationData.accessToken = tokenData.access_token;
+      if (tokenData.refresh_token) {
+        integrationData.refreshToken = tokenData.refresh_token;
+      }
+      if (tokenData.expires_in) {
+        integrationData.expiresAt = Date.now() + tokenData.expires_in * 1000;
+      }
+      if (tokenData.refresh_token_expires_in) {
+        integrationData.refreshTokenExpiresAt =
+          Date.now() + tokenData.refresh_token_expires_in * 1000;
+      }
+      integrationData.updatedAt = new Date().toISOString();
+
+      await saveIntegration(integrationData);
+      console.log('GitHub token refreshed successfully.');
+      return integrationData;
+    }
+
+    if (isBadGithubRefreshTokenError(tokenData)) {
+      console.warn(
+        'GitHub refresh token is invalid or expired. Clearing the saved GitHub connection; reconnect GitHub to continue.',
+      );
+      await deleteIntegration();
+      return null;
+    }
+
+    console.error(
+      'Failed to refresh GitHub token, no access_token returned:',
+      tokenData,
+    );
+  } catch (error) {
+    console.error('Failed to refresh GitHub token:', error);
+  }
+
+  return integrationData;
+}