fix(webapp): smooth out the first GitHub deployment in onboarding

Improve the first GitHub deployment experience: Deploy now explains when a branch doesn't exist on GitHub, a harmless first-build cache message no longer shows as an error, the deployment panel stays on screen after the first deploy finishes, the empty development Tasks page uses the new setup layout, and the deployment setup screen is vertically centered.

Mono-RevId: 07d4623e6fbe912906e1976f513f962c5ec42aa6

Author: d-cs

.server-changes/deploy-now-missing-branch.md

@@ -0,0 +1,6 @@
+---
+area: webapp
+type: fix
+---
+
+"Deploy now" now tells you when the branch doesn't exist on GitHub instead of showing a generic error, and a first deployment no longer flags a harmless build-cache message as an error.

apps/webapp/app/components/BlankStatePanels.tsx

@@ -4,6 +4,7 @@ import {
   BellAlertIcon,
   BookOpenIcon,
   ChatBubbleLeftRightIcon,
+  CheckIcon,
   PlusIcon,
   QuestionMarkCircleIcon,
   Squares2X2Icon,
@@ -116,10 +117,17 @@ function DeployDocsLinks() {
   );
 }
 
-export function HasNoTasksDev({ initializedAt }: { initializedAt: Date | string | null }) {
+export function HasNoTasksDev({
+  initializedAt,
+  enhanced = false,
+}: {
+  initializedAt: Date | string | null;
+  enhanced?: boolean;
+}) {
   const { isConnected } = useDevPresence();
   const initialized = !!initializedAt;
   const devConnected = isConnected === true;
+  const complete = <CheckIcon className="size-5 text-success" aria-label="Complete" />;
 
   return (
     <PackageManagerProvider>
@@ -163,49 +171,88 @@ export function HasNoTasksDev({ initializedAt }: { initializedAt: Date | string
             </div>
           </>
         )}
-        <StepNumber
-          stepNumber="1"
-          title={initialized ? "Project initialized" : "Initialize your project"}
-          complete={initialized}
-        />
-        <StepContentContainer>
-          {initialized ? (
-            <Paragraph>
-              Your project is initialized. Your tasks live in the{" "}
-              <InlineCode variant="small">trigger</InlineCode> directory.
-            </Paragraph>
-          ) : (
-            <>
-              <InitCommandV3 />
-              <Paragraph spacing>
-                Run this in an existing project. You'll notice a new folder called{" "}
-                <InlineCode variant="small">trigger</InlineCode> with a few example tasks to help
-                you get started.
-              </Paragraph>
-            </>
-          )}
-        </StepContentContainer>
-        <StepNumber
-          stepNumber="2"
-          title={devConnected ? "Dev server connected" : "Start the dev server"}
-          complete={devConnected}
-        />
-        <StepContentContainer>
-          {devConnected ? (
-            <Paragraph>
-              Your dev server is connected. Your tasks will appear here automatically as soon as
-              they register.
-            </Paragraph>
-          ) : (
-            <>
-              <TriggerDevStepV3 />
-              <Paragraph spacing>
-                Keep this running while you develop. Once your tasks register, this page updates
-                automatically.
-              </Paragraph>
-            </>
-          )}
-        </StepContentContainer>
+        {enhanced ? (
+          <div>
+            <SettingsRow
+              bordered={false}
+              title={initialized ? "Project initialized" : "Initialize your project"}
+              description={
+                initialized ? (
+                  <>
+                    Your project is initialized. Your tasks live in the{" "}
+                    <InlineCode variant="extra-small">trigger</InlineCode> directory.
+                  </>
+                ) : (
+                  <>
+                    Run this in an existing project. You'll notice a new folder called{" "}
+                    <InlineCode variant="extra-small">trigger</InlineCode> with a few example tasks
+                    to help you get started.
+                  </>
+                )
+              }
+              action={initialized ? complete : undefined}
+            />
+            {!initialized && <InitCommandV3 />}
+            <SettingsRow
+              className="border-t border-grid-dimmed"
+              bordered={false}
+              title={devConnected ? "Dev server connected" : "Start the dev server"}
+              description={
+                devConnected
+                  ? "Your dev server is connected. Your tasks will appear here automatically as soon as they register."
+                  : "Keep this running while you develop. Once your tasks register, this page updates automatically."
+              }
+              action={devConnected ? complete : undefined}
+            />
+            {!devConnected && <TriggerDevStepV3 />}
+          </div>
+        ) : (
+          <>
+            <StepNumber
+              stepNumber="1"
+              title={initialized ? "Project initialized" : "Initialize your project"}
+              complete={initialized}
+            />
+            <StepContentContainer>
+              {initialized ? (
+                <Paragraph>
+                  Your project is initialized. Your tasks live in the{" "}
+                  <InlineCode variant="small">trigger</InlineCode> directory.
+                </Paragraph>
+              ) : (
+                <>
+                  <InitCommandV3 />
+                  <Paragraph spacing>
+                    Run this in an existing project. You'll notice a new folder called{" "}
+                    <InlineCode variant="small">trigger</InlineCode> with a few example tasks to
+                    help you get started.
+                  </Paragraph>
+                </>
+              )}
+            </StepContentContainer>
+            <StepNumber
+              stepNumber="2"
+              title={devConnected ? "Dev server connected" : "Start the dev server"}
+              complete={devConnected}
+            />
+            <StepContentContainer>
+              {devConnected ? (
+                <Paragraph>
+                  Your dev server is connected. Your tasks will appear here automatically as soon as
+                  they register.
+                </Paragraph>
+              ) : (
+                <>
+                  <TriggerDevStepV3 />
+                  <Paragraph spacing>
+                    Keep this running while you develop. Once your tasks register, this page updates
+                    automatically.
+                  </Paragraph>
+                </>
+              )}
+            </StepContentContainer>
+          </>
+        )}
       </div>
     </PackageManagerProvider>
   );

apps/webapp/app/components/deployments/GitHubDeploymentOnboarding.test.ts

@@ -10,7 +10,7 @@ import { LocaleContextProvider } from "~/components/primitives/LocaleProvider";
 import { expect, it } from "vitest";
 import { ShortcutsProvider } from "~/components/primitives/ShortcutsProvider";
 import { OperatingSystemContextProvider } from "~/components/primitives/OperatingSystemProvider";
-import { GitHubDeploymentOnboarding } from "./GitHubDeploymentOnboarding";
+import { deployNowRequestError, GitHubDeploymentOnboarding } from "./GitHubDeploymentOnboarding";
 import { OnboardingDeploymentLogs } from "./OnboardingDeploymentLogs";
 
 function render(node: React.ReactNode) {
@@ -276,3 +276,11 @@ it("keeps the legacy connected-repository form on its original layout and explic
     expect(html.includes(">Save<")).toBe(true);
   }
 });
+
+it("tells the user a missing branch has to be pushed instead of asking them to retry", () => {
+  const missing = 'The branch "test" doesn\'t exist in acme/app. Push it to GitHub, then deploy.';
+  expect(deployNowRequestError({ code: "BRANCH_NOT_FOUND", error: missing })).toBe(missing);
+  expect(deployNowRequestError({ error: "Couldn't start the deploy" })).toBe(
+    "Couldn't start the deployment. Try again."
+  );
+});

apps/webapp/app/components/deployments/GitHubDeploymentOnboarding.tsx

@@ -8,6 +8,12 @@ import { LinkButton } from "~/components/primitives/Buttons";
 import { Spinner } from "~/components/primitives/Spinner";
 import { VercelAtomicDeploymentNotice } from "./VercelAtomicDeploymentNotice";
 
+export function deployNowRequestError(data: { code?: string; error?: string }): string {
+  // Retrying can't fix a missing branch, so say what the user has to do instead.
+  if (data.code === "BRANCH_NOT_FOUND" && data.error) return data.error;
+  return "Couldn't start the deployment. Try again.";
+}
+
 const statusTitles: Record<WorkerDeploymentStatus, string> = {
   PENDING: "Your deployment is queued",
   INSTALLING: "Installing dependencies",

apps/webapp/app/components/deployments/GitHubDeploymentOnboardingPanel.tsx

@@ -9,7 +9,11 @@ import {
 } from "~/hooks/useOnboardingDeploymentLogs";
 import { deployNowPath } from "~/routes/resources.orgs.$organizationSlug.projects.$projectParam.env.$envParam.deploy-now";
 import { OnboardingDeploymentLogs } from "./OnboardingDeploymentLogs";
-import { GitHubDeploymentOnboarding, type OnboardingBuild } from "./GitHubDeploymentOnboarding";
+import {
+  deployNowRequestError,
+  GitHubDeploymentOnboarding,
+  type OnboardingBuild,
+} from "./GitHubDeploymentOnboarding";
 
 export function GitHubDeploymentOnboardingPanel({
   renderConnection,
@@ -49,7 +53,7 @@ export function GitHubDeploymentOnboardingPanel({
   });
   const [settingsDirty, setSettingsDirty] = useState(false);
   const [settingsSaving, setSettingsSaving] = useState(false);
-  const fetcher = useFetcher<{ ok: boolean; code?: string; vercelUrl?: string }>();
+  const fetcher = useFetcher<{ ok: boolean; code?: string; error?: string; vercelUrl?: string }>();
   const revalidator = useRevalidator();
   const [delayed, setDelayed] = useState(false);
   const submitting = fetcher.state !== "idle";
@@ -80,7 +84,7 @@ export function GitHubDeploymentOnboardingPanel({
       historyHref={build ? historyHref : undefined}
       requestError={
         fetcher.data?.ok === false && !submitting && !build
-          ? "Couldn't start the deployment. Try again."
+          ? deployNowRequestError(fetcher.data)
           : undefined
       }
       deployAction={

apps/webapp/app/components/layout/AppLayout.tsx

@@ -65,19 +65,26 @@ export function MainCenteredContainer({
 }: {
   children: React.ReactNode;
   className?: string;
-  variant?: "default" | "onboarding";
+  variant?: "default" | "onboarding" | "centered";
 }) {
   return (
     <div
       className={cn(
         "h-full w-full overflow-y-auto scrollbar-thin scrollbar-track-transparent scrollbar-thumb-surface-control",
-        variant === "onboarding" && "flex flex-col p-4 lg:p-0"
+        variant === "onboarding" && "flex flex-col p-4 lg:p-0",
+        variant === "centered" && "flex flex-col"
       )}
     >
       <div
         className={cn(
           "mx-auto max-w-xs p-1",
-          variant === "onboarding" ? "m-auto lg:mx-auto lg:mb-0 lg:mt-[22vh]" : "mt-6 md:mt-[22vh]",
+          variant === "onboarding"
+            ? "m-auto lg:mx-auto lg:mb-0 lg:mt-[22vh]"
+            : variant === "centered"
+              ? // Auto margins center the block when it fits and collapse to 0 when it
+                // overflows, so tall content scrolls from the top instead of clipping.
+                "my-auto py-6"
+              : "mt-6 md:mt-[22vh]",
           className
         )}
       >

apps/webapp/app/hooks/deploymentLogFilter.ts

@@ -0,0 +1,14 @@
+import type { DeploymentLogEntry } from "~/components/runs/v3/deploymentLogsCache";
+
+// BuildKit reports a missing registry cache as a step ERROR, then builds without it.
+// That always happens on a project's first build, so keep the line for history but
+// don't let it read (or count) as a failure.
+const REGISTRY_CACHE_MISS =
+  /^#\d+ ERROR: failed to configure registry cache importer: \S+: not found$/;
+
+export function classifyDeploymentLog(entry: DeploymentLogEntry): DeploymentLogEntry {
+  if (entry.level === "error" && REGISTRY_CACHE_MISS.test(entry.message.trim())) {
+    return { ...entry, level: "info" };
+  }
+  return entry;
+}

apps/webapp/app/hooks/deploymentOnboardingLatch.test.ts

@@ -0,0 +1,54 @@
+import { expect, it } from "vitest";
+import { resolveOnboardingLatch } from "./deploymentOnboardingLatch";
+
+const building = {
+  showGitHubOnboarding: true,
+  onboardingDetails: { deployment: { shortCode: "abc", status: "BUILDING" as const } },
+};
+const idle = { showGitHubOnboarding: true, onboardingDetails: undefined };
+const done = { showGitHubOnboarding: false, onboardingDetails: undefined };
+const here = "/orgs/o/projects/p/env/prod/deployments";
+
+it("keeps showing the watched build after the loader stops selecting onboarding", () => {
+  const watching = resolveOnboardingLatch(undefined, building, here);
+  expect(watching).toMatchObject({ shown: building, latched: false });
+
+  const completed = resolveOnboardingLatch(watching.latch, done, here);
+  expect(completed).toMatchObject({ shown: building, latched: true });
+
+  // Later polls keep it on screen too.
+  expect(resolveOnboardingLatch(completed.latch, done, here).shown).toBe(building);
+});
+
+it("keeps showing it when the loader drops onboarding entirely (tasks appeared)", () => {
+  const { latch } = resolveOnboardingLatch(undefined, building, here);
+  expect(resolveOnboardingLatch(latch, undefined, here)).toMatchObject({
+    shown: building,
+    latched: true,
+  });
+});
+
+it("lets the normal page through after navigating", () => {
+  const { latch } = resolveOnboardingLatch(undefined, building, here);
+  expect(resolveOnboardingLatch(latch, done, `${here}/abc`)).toEqual({
+    latch: undefined,
+    shown: done,
+    latched: false,
+  });
+});
+
+it("doesn't latch before a build has started", () => {
+  const { latch } = resolveOnboardingLatch(undefined, idle, here);
+  expect(latch).toBeUndefined();
+  expect(resolveOnboardingLatch(latch, done, here).shown).toBe(done);
+});
+
+it("keeps the same latch while the loader data is unchanged", () => {
+  const first = resolveOnboardingLatch(undefined, building, here);
+  expect(resolveOnboardingLatch(first.latch, building, here).latch).toBe(first.latch);
+});
+
+it("keeps the same latch when a caller rebuilds the wrapper object each render", () => {
+  const first = resolveOnboardingLatch(undefined, { ...building }, here);
+  expect(resolveOnboardingLatch(first.latch, { ...building }, here).latch).toBe(first.latch);
+});

apps/webapp/app/hooks/deploymentOnboardingLatch.ts

@@ -0,0 +1,33 @@
+import type { WorkerDeploymentStatus } from "@trigger.dev/database";
+
+type OnboardingState = {
+  showGitHubOnboarding: boolean;
+  onboardingDetails?: { deployment: { shortCode: string; status: WorkerDeploymentStatus } };
+};
+
+export type OnboardingLatch<T> = { value: T; location: string } | undefined;
+
+/**
+ * Keeps a watched first build on screen after the loader stops selecting onboarding, until the
+ * user navigates away (or reloads, which starts without a latch).
+ */
+export function resolveOnboardingLatch<T extends OnboardingState>(
+  latch: OnboardingLatch<T>,
+  current: T | undefined,
+  location: string
+): { latch: OnboardingLatch<T>; shown: T | undefined; latched: boolean } {
+  if (current?.showGitHubOnboarding) {
+    if (!current.onboardingDetails) return { latch: undefined, shown: current, latched: false };
+    const next =
+      latch?.value.onboardingDetails === current.onboardingDetails && latch.location === location
+        ? latch
+        : { value: current, location };
+    return { latch: next, shown: current, latched: false };
+  }
+
+  if (latch && latch.location === location) {
+    return { latch, shown: latch.value, latched: true };
+  }
+
+  return { latch: undefined, shown: current, latched: false };
+}

apps/webapp/app/hooks/useDeploymentLogs.ts

@@ -2,6 +2,7 @@ import { S2, S2Error } from "@s2-dev/streamstore";
 import { DeploymentEventFromString } from "@trigger.dev/core/v3/schemas";
 import type { WorkerDeploymentStatus } from "@trigger.dev/database";
 import { useEffect, useState } from "react";
+import { classifyDeploymentLog } from "./deploymentLogFilter";
 import {
   deploymentLogsCache,
   type DeploymentLogEntry,
@@ -72,7 +73,7 @@ export function useDeploymentLogs({ eventStream, status }: UseDeploymentLogsOpti
     };
 
     const push = (entry: DeploymentLogEntry) => {
-      pending.push(entry);
+      pending.push(classifyDeploymentLog(entry));
       flushTimer ??= setTimeout(flush, 0);
     };