feat(cli): surface preview deployment links in the PR header

getChecks now fetches the commit's deployments via a single gh api graphql
query (commit.deployments + latestStatus), in parallel with check-runs, and
resolves one link per environment — the latest successful deployment with an
https URL (mirrors hosted Stage's resolveDeploymentLinks). The header's
already-vendored deployment button/popover renders them with no UI change.
Replaces the previous always-empty deploymentLinks (and the inaccurate
"needs a GitHub App" note — the Deployments data is readable via gh).

Author: dastratakos

packages/cli/src/__tests__/pull-request.routes.test.ts

@@ -110,6 +110,37 @@ const MERGE_JSON = JSON.stringify({
 		},
 	},
 });
+// Deployments GraphQL response (newest-first). Exercises dedupe-by-environment,
+// skipping non-success and non-https/null URLs.
+const DEPLOYMENTS_JSON = JSON.stringify({
+	data: {
+		repository: {
+			object: {
+				deployments: {
+					nodes: [
+						{
+							environment: "Preview",
+							latestStatus: { state: "SUCCESS", environmentUrl: "https://preview-2.example.app" },
+						},
+						{
+							environment: "Preview",
+							latestStatus: { state: "SUCCESS", environmentUrl: "https://preview-1.example.app" },
+						},
+						{
+							environment: "Production",
+							latestStatus: { state: "SUCCESS", environmentUrl: "https://prod.example.app" },
+						},
+						{
+							environment: "Staging",
+							latestStatus: { state: "FAILURE", environmentUrl: "https://staging.example.app" },
+						},
+						{ environment: "NoUrl", latestStatus: { state: "SUCCESS", environmentUrl: null } },
+					],
+				},
+			},
+		},
+	},
+});
 
 beforeEach(async () => {
 	tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), "stage-cli-pr-routes-"));
@@ -143,6 +174,7 @@ async function writeFakeGh(fixtures: {
 	reviews?: string;
 	checks?: string;
 	merge?: string;
+	deployments?: string;
 }): Promise<void> {
 	const dir = path.join(binDir, "fixtures");
 	await fs.mkdir(dir, { recursive: true });
@@ -155,13 +187,15 @@ async function writeFakeGh(fixtures: {
 		write("reviews.json", fixtures.reviews),
 		write("checks.json", fixtures.checks),
 		write("merge.json", fixtures.merge),
+		write("deployments.json", fixtures.deployments),
 	]);
 	const script = `#!/bin/sh
 dir="${dir}"
 emit() { [ -f "$dir/$1" ] && cat "$dir/$1" || exit 1; }
 all="$*"
 if [ "$1" = "pr" ] && [ "$2" = "view" ]; then emit pr.json
-elif [ "$1" = "api" ] && [ "$2" = "graphql" ]; then emit merge.json
+elif [ "$1" = "api" ] && [ "$2" = "graphql" ]; then
+  case "$all" in *deployments*) emit deployments.json ;; *) emit merge.json ;; esac
 elif [ "$1" = "api" ]; then
   case "$all" in
     *check-runs*) emit checks.json ;;
@@ -288,6 +322,23 @@ describe("pull-request API", () => {
 		});
 	});
 
+	it("returns one deployment link per environment (latest success, https only)", async () => {
+		await writeFakeGh({ checks: CHECKS_JSON, deployments: DEPLOYMENTS_JSON });
+		const runId = insertRun(GITHUB_ORIGIN);
+		const res = await request(
+			await start(),
+			`/api/runs/${runId}/pull-request/checks?headSha=${SHA}`,
+		);
+		expect(res.status).toBe(200);
+		const body = JSON.parse(res.body) as ChecksResponse;
+		// Preview deduped to the newest success; Production kept; Staging (failure)
+		// and NoUrl (null url) dropped.
+		expect(body.deploymentLinks).toEqual([
+			{ environment: "Preview", url: "https://preview-2.example.app" },
+			{ environment: "Production", url: "https://prod.example.app" },
+		]);
+	});
+
 	it("rejects a checks request without a valid headSha", async () => {
 		await writeFakeGh({ checks: CHECKS_JSON });
 		const runId = insertRun(GITHUB_ORIGIN);

packages/cli/src/github/pull-request.ts

@@ -3,6 +3,7 @@ import {
 	CHECK_ITEM_SOURCE,
 	type CheckItem,
 	type ChecksResponse,
+	type DeploymentLink,
 	type GitHubPullRequest,
 	type GitHubUser,
 	type MergeStatusInfo,
@@ -206,20 +207,11 @@ function deriveCiState(items: CheckItem[]): ChecksResponse["state"] {
 	return anyPending ? PULL_REQUEST_CI_STATUS.PENDING : PULL_REQUEST_CI_STATUS.SUCCESS;
 }
 
-/**
- * CI check runs for `headSha`. Deployment links require a GitHub App
- * integration the CLI doesn't have, so `deploymentLinks` is always empty here.
- */
-export async function getChecks(
+async function getCheckRunItems(
 	repoRoot: string,
 	repo: GitHubRepo,
 	headSha: string,
-): Promise<ChecksResponse> {
-	const empty: ChecksResponse = {
-		state: PULL_REQUEST_CI_STATUS.NONE,
-		items: [],
-		deploymentLinks: [],
-	};
+): Promise<CheckItem[]> {
 	try {
 		// `--slurp` wraps every page into one JSON array (`[{page}, {page}, …]`);
 		// without it, `--paginate` concatenates raw page objects, which isn't valid
@@ -234,14 +226,116 @@ export async function getChecks(
 			repoRoot,
 		);
 		const parsed = z.array(GhCheckRunsSchema).safeParse(JSON.parse(stdout));
-		if (!parsed.success) return empty;
-		const items = parsed.data.flatMap((page) => page.check_runs).map(toCheckItem);
-		return { state: deriveCiState(items), items, deploymentLinks: [] };
+		if (!parsed.success) return [];
+		return parsed.data.flatMap((page) => page.check_runs).map(toCheckItem);
 	} catch {
-		return empty;
+		return [];
 	}
 }
 
+// ─── Deployments ──────────────────────────────────────────────────────────────
+
+// Fetch the commit's deployments + each one's latest status in a single query,
+// newest-first, so dedupe-by-environment below keeps the most recent per env.
+const DEPLOYMENTS_QUERY = `query GetDeployments($owner: String!, $repo: String!, $sha: GitObjectID!) {
+  repository(owner: $owner, name: $repo) {
+    object(oid: $sha) {
+      ... on Commit {
+        deployments(first: 20, orderBy: { field: CREATED_AT, direction: DESC }) {
+          nodes { environment latestStatus { state environmentUrl } }
+        }
+      }
+    }
+  }
+}`;
+
+const GhDeploymentsSchema = z.object({
+	data: z.object({
+		repository: z
+			.object({
+				object: z
+					.object({
+						deployments: z.object({
+							nodes: z.array(
+								z.object({
+									environment: z.string(),
+									latestStatus: z
+										.object({ state: z.string(), environmentUrl: z.string().nullable() })
+										.nullable(),
+								}),
+							),
+						}),
+					})
+					.nullable(),
+			})
+			.nullable(),
+	}),
+});
+
+/**
+ * Preview/deployment links for `headSha`: one per environment, keeping the
+ * latest successful deployment with an https URL (mirrors hosted Stage's
+ * resolveDeploymentLinks). Returns [] on any failure so checks still render.
+ */
+async function getDeploymentLinks(
+	repoRoot: string,
+	repo: GitHubRepo,
+	headSha: string,
+): Promise<DeploymentLink[]> {
+	try {
+		const stdout = await gh(
+			[
+				"api",
+				"graphql",
+				"-f",
+				`query=${DEPLOYMENTS_QUERY}`,
+				"-F",
+				`owner=${repo.owner}`,
+				"-F",
+				`repo=${repo.repo}`,
+				"-F",
+				`sha=${headSha}`,
+			],
+			repoRoot,
+		);
+		const parsed = GhDeploymentsSchema.safeParse(JSON.parse(stdout));
+		if (!parsed.success) return [];
+		const nodes = parsed.data.data.repository?.object?.deployments.nodes ?? [];
+		const byEnvironment = new Map<string, DeploymentLink>();
+		for (const node of nodes) {
+			const url = node.latestStatus?.environmentUrl;
+			if (
+				node.latestStatus?.state === "SUCCESS" &&
+				url &&
+				url.startsWith("https://") &&
+				!byEnvironment.has(node.environment)
+			) {
+				byEnvironment.set(node.environment, { environment: node.environment, url });
+			}
+		}
+		return [...byEnvironment.values()];
+	} catch {
+		return [];
+	}
+}
+
+/**
+ * CI check runs plus preview-deployment links for `headSha`. Runs the two gh
+ * reads in parallel; each degrades to empty independently so a failure in one
+ * never blanks the other.
+ */
+export async function getChecks(
+	repoRoot: string,
+	repo: GitHubRepo,
+	headSha: string,
+): Promise<ChecksResponse> {
+	const [items, deploymentLinks] = await Promise.all([
+		getCheckRunItems(repoRoot, repo, headSha),
+		getDeploymentLinks(repoRoot, repo, headSha),
+	]);
+	return { state: deriveCiState(items), items, deploymentLinks };
+}
+
 // ─── Reviews ────────────────────────────────────────────────────────────────
 
 // REST reviews are returned oldest-first, so iterating and overwriting per login