[Feat] Guide self-hosted Linear OAuth setup

apps/api/src/handlers/linear/index.ts

@@ -23,7 +23,11 @@ import {
 import { buildTaskStartingText } from '@roomote/communication/chat-messages';
 import { getRedis } from '@roomote/redis';
 import { postRouterDebugMessage } from '@roomote/slack';
-import { setTrustedRunActingUserOnSuccess } from '@roomote/db/server';
+import {
+  db,
+  resolveDeploymentEnvVar,
+  setTrustedRunActingUserOnSuccess,
+} from '@roomote/db/server';
 import {
   createMcpOauthReplay,
   findLinearDeploymentMcpConnectionByIdentity,
@@ -302,7 +306,11 @@ linear.post('/', async (c) => {
 
   // Verify webhook signature
   const signature = headers['linear-signature'] ?? '';
-  const webhookSecret = Env.R_LINEAR_WEBHOOK_SECRET;
+  const webhookSecret = await resolveDeploymentEnvVar(
+    'R_LINEAR_WEBHOOK_SECRET',
+    db,
+    { R_LINEAR_WEBHOOK_SECRET: Env.R_LINEAR_WEBHOOK_SECRET },
+  );
 
   if (!webhookSecret) {
     console.error('[LinearWebhook] R_LINEAR_WEBHOOK_SECRET not configured');

apps/docs/integrations/linear.mdx

@@ -14,16 +14,20 @@ priority, or discussion.
 
 ## Setup
 
-For self-hosted deployments, create a Linear OAuth application before
-connecting the workspace. Configure its callback as
-`<R_PUBLIC_URL>/api/mcp-oauth/callback`, then set
-`R_LINEAR_CLIENT_ID`, `R_LINEAR_CLIENT_SECRET`, and
-`R_LINEAR_WEBHOOK_SECRET` on the Roomote deployment.
-
 <Steps>
-  <Step title="Connect Linear">
-    In Roomote, go to **Settings > Integrations** and connect your Linear
-    workspace.
+  <Step title="Set up the OAuth app">
+    On a self-hosted deployment, an administrator goes to **Settings >
+    Integrations**, selects **Set it up**, and then selects **Create Linear
+    app** to open the pre-filled manifest. The app name defaults to the same
+    `roomote-<deployment-hostname>` convention used by the GitHub setup. After
+    creating the private app, copy its client ID, client secret, and webhook
+    secret back into Roomote. Roomote encrypts the saved credentials.
+  </Step>
+  <Step title="Connect the workspace">
+    Select **Enable Linear**, approve the app in Linear, and return to Roomote.
+    Deployments that provide `R_LINEAR_CLIENT_ID`,
+    `R_LINEAR_CLIENT_SECRET`, and `R_LINEAR_WEBHOOK_SECRET` in the runtime
+    environment continue to use those values and skip the in-app setup.
   </Step>
   <Step title="Link your user account">
     Link your Linear identity when prompted so Roomote can associate issue

apps/web/src/app/api/mcp-oauth/initiate/[connectionId]/route.ts

@@ -34,7 +34,7 @@ import {
 import { authorize } from '@/lib/server';
 import { bootstrapWebRuntimeEnv } from '@/lib/server/bootstrap-runtime-env';
 import { getPublicAppUrl } from '@/lib/server/get-public-app-url';
-import { resolveStaticOauthClientInformation } from '@/lib/server/mcp-static-oauth';
+import { resolveDeploymentStaticOauthClientInformation } from '@/lib/server/deployment-static-oauth';
 
 export const runtime = 'nodejs';
 
@@ -147,13 +147,6 @@ function getOAuthServerMetadataOverride(
   };
 }
 
-function getStaticClientInformation(
-  env: unknown,
-  integration: McpIntegration,
-): OAuthClientInformation | undefined {
-  return resolveStaticOauthClientInformation(env, integration);
-}
-
 export async function GET(
   request: Request,
   { params }: { params: Promise<{ connectionId: string }> },
@@ -229,22 +222,20 @@ export async function GET(
       connection.connectionRole,
     );
 
-    let clientInfo: OAuthClientInformation | undefined =
-      await getClientInformation(connectionId, {
+    const staticClientInfo =
+      await resolveDeploymentStaticOauthClientInformation(webEnv, integration);
+    let clientInfo: OAuthClientInformation | undefined;
+
+    if (staticClientInfo) {
+      // Configured deployment credentials are authoritative. Replacing the
+      // stored client also migrates connections created by the old dynamic
+      // registration flow before their next authorization or token refresh.
+      await storeClientInformation(connectionId, staticClientInfo, redirectUri);
+      clientInfo = staticClientInfo;
+    } else {
+      clientInfo = await getClientInformation(connectionId, {
         expectedRedirectUri: redirectUri,
       });
-
-    if (!clientInfo) {
-      const staticClientInfo = getStaticClientInformation(webEnv, integration);
-
-      if (staticClientInfo) {
-        await storeClientInformation(
-          connectionId,
-          staticClientInfo,
-          redirectUri,
-        );
-        clientInfo = staticClientInfo;
-      }
     }
 
     if (!clientInfo && serverMetadata.registration_endpoint) {