feat(build): support dSYMs with IPA uploads

apps/cli-docs/src/fragments/commands/build.md

@@ -10,6 +10,9 @@ sentry build upload ./app-release.apk
 sentry build upload ./MyApp.xcarchive
 sentry build upload ./MyApp.ipa
 
+# Attach dSYMs to an IPA upload (bundle, directory of bundles, or ZIP; repeatable)
+sentry build upload ./MyApp.ipa --dsym ./MyApp.app.dSYM --dsym ./Frameworks.dSYMs.zip
+
 # Upload with a build configuration and release notes
 sentry build upload ./app.aab --build-configuration Release --release-notes "Nightly"
 
@@ -38,6 +41,10 @@ sentry build download 1234567890 --json
   images (that required native macOS frameworks), so the server sees the raw
   `.car` rather than a per-image breakdown. XCArchive symlinks and Unix file
   permissions are preserved.
+- `--dsym` attaches debug symbols to an **IPA** upload (IPAs are often missing
+  dSYMs after app thinning). Each value may be a `.dSYM` bundle, a directory of
+  bundles, or a ZIP of either, and the flag is repeatable. It only applies when
+  uploading a single IPA.
 - Multiple paths may be uploaded at once; the command exits non-zero if any
   build fails to upload.
 - Git metadata (commit, branch, PR number, repo) is **auto-collected in CI**

packages/cli/plugins/sentry-cli/skills/sentry-cli/references/build.md

@@ -19,6 +19,7 @@ Upload builds to a project
 - `--build-configuration <value> - Build configuration for the upload (defaults to the current version)`
 - `--release-notes <value> - Release notes for the build`
 - `--install-group <value>... - Install group(s) for this build (repeatable); builds sharing a group show updates for each other`
+- `--dsym <value>... - Path to a dSYM bundle, a directory of dSYM bundles, or a ZIP of either to include with an IPA upload (repeatable)`
 - `--head-sha <value> - VCS commit SHA (defaults to the current commit)`
 - `--base-sha <value> - VCS base commit SHA (defaults to the merge-base with the base ref)`
 - `--vcs-provider <value> - VCS provider (defaults to the current remote's provider)`
@@ -47,6 +48,9 @@ sentry build upload ./app-release.apk
 sentry build upload ./MyApp.xcarchive
 sentry build upload ./MyApp.ipa
 
+# Attach dSYMs to an IPA upload (bundle, directory of bundles, or ZIP; repeatable)
+sentry build upload ./MyApp.ipa --dsym ./MyApp.app.dSYM --dsym ./Frameworks.dSYMs.zip
+
 # Upload with a build configuration and release notes
 sentry build upload ./app.aab --build-configuration Release --release-notes "Nightly"
 

packages/cli/src/commands/build/upload.ts

@@ -16,6 +16,7 @@ import {
   uploadBuild,
 } from "../../lib/api/preprod-artifacts.js";
 import {
+  collectDsymEntries,
   detectBuildFormat,
   normalizeBuildDirectory,
   normalizeBuildFile,
@@ -58,6 +59,7 @@ type UploadFlags = {
   "build-configuration"?: string;
   "release-notes"?: string;
   "install-group"?: string[];
+  dsym?: string[];
 } & VcsFlags;
 
 /** Result for a single uploaded path. */
@@ -103,7 +105,8 @@ async function uploadOne(
   path: string,
   org: string,
   project: string,
-  metadata: BuildUploadMetadata
+  metadata: BuildUploadMetadata,
+  dsymPaths: string[]
 ): Promise<string> {
   let info: Awaited<ReturnType<typeof stat>>;
   try {
@@ -119,6 +122,12 @@ async function uploadOne(
   // validation refuses arbitrary directories so a stray `sentry build upload ./`
   // can't sweep up source, .git/, or secrets.
   if (info.isDirectory()) {
+    if (dsymPaths.length > 0) {
+      throw new ValidationError(
+        "--dsym can only be used with an IPA upload",
+        "dsym"
+      );
+    }
     validateXcarchiveDirectory(path);
     const normalized = await normalizeBuildDirectory(path, plugin);
     return await uploadBuild({ org, project, content: normalized, metadata });
@@ -135,8 +144,16 @@ async function uploadOne(
 
   let normalized: Buffer;
   if (format === "ipa") {
-    normalized = normalizeIpa(content, plugin);
+    const dsymEntries =
+      dsymPaths.length > 0 ? await collectDsymEntries(dsymPaths) : [];
+    normalized = normalizeIpa(content, plugin, dsymEntries);
   } else if (format === "apk" || format === "aab") {
+    if (dsymPaths.length > 0) {
+      throw new ValidationError(
+        "--dsym can only be used with an IPA upload",
+        "dsym"
+      );
+    }
     normalized = normalizeBuildFile(path, content, plugin);
   } else {
     throw new ValidationError(
@@ -161,6 +178,7 @@ export const uploadCommand = buildCommand({
       "  sentry build upload ./app-release.apk\n" +
       "  sentry build upload ./MyApp.xcarchive\n" +
       "  sentry build upload ./MyApp.ipa --build-configuration Release\n" +
+      "  sentry build upload ./MyApp.ipa --dsym ./MyApp.app.dSYM\n" +
       "  sentry build upload ./app.aab --install-group qa --install-group beta",
   },
   output: {
@@ -197,6 +215,14 @@ export const uploadCommand = buildCommand({
         optional: true,
         variadic: true,
       },
+      dsym: {
+        kind: "parsed",
+        parse: String,
+        brief:
+          "Path to a dSYM bundle, a directory of dSYM bundles, or a ZIP of either to include with an IPA upload (repeatable)",
+        optional: true,
+        variadic: true,
+      },
       "head-sha": {
         kind: "parsed",
         parse: String,
@@ -274,6 +300,16 @@ export const uploadCommand = buildCommand({
     }
     const { org, project } = resolved;
 
+    const dsymPaths = flags.dsym ?? [];
+    // dSYM inputs apply to the whole command, so their target would be
+    // ambiguous when a single invocation uploads more than one build.
+    if (dsymPaths.length > 0 && paths.length > 1) {
+      throw new ValidationError(
+        "--dsym can only be used when uploading exactly one IPA file",
+        "dsym"
+      );
+    }
+
     if (flags["force-git-metadata"] && flags["no-git-metadata"]) {
       throw new ValidationError(
         "--force-git-metadata and --no-git-metadata cannot be used together",
@@ -301,7 +337,14 @@ export const uploadCommand = buildCommand({
     const builds: BuildUploadEntry[] = [];
     for (const path of paths) {
       try {
-        const artifactUrl = await uploadOne(this, path, org, project, metadata);
+        const artifactUrl = await uploadOne(
+          this,
+          path,
+          org,
+          project,
+          metadata,
+          dsymPaths
+        );
         builds.push({ path, artifactUrl, error: null });
       } catch (err) {
         const message = err instanceof Error ? err.message : String(err);