feat(build): add musl binaries for Alpine Linux support (#762)

## Summary

Closes #754

- Add `sentry-linux-x64-musl` and `sentry-linux-arm64-musl` native
binaries using Bun's built-in musl cross-compilation targets
- Add runtime musl detection so the install script and self-upgrade
download the correct binary variant
- Add Alpine Docker smoke test in CI to verify musl binaries work

## Changes

**Build system** (`script/build.ts`): Extend `BuildTarget` with `libc?:
"musl"`, add 2 musl entries to `ALL_TARGETS`, update
`getPackageName`/`getBunTarget`/`parseTarget` to handle musl suffix.

**Runtime detection** (`src/lib/binary.ts`): New `isMusl()` function
checks for `/lib/ld-musl-<arch>.so.1` (fast stat) with `ldd --version`
fallback. `getPlatformBinaryName()` appends `-musl` on musl systems —
auto-propagates to upgrade and download URLs.

**Install script** (`install`): `detect_musl` function with same two
heuristics. `libc_suffix` applied to both nightly (GHCR) and stable
(GitHub Releases) download paths. `libc` tag added to error telemetry.

**CI** (`.github/workflows/ci.yml`): `linux-x64-musl` and
`linux-arm64-musl` added to full build matrix (cross-compiled on
ubuntu-latest). Alpine Docker smoke test for x64-musl.

**No changes needed** to `.craft.yml` (regex already matches), Homebrew
formula (correctly excludes musl), or downstream consumers of
`getPlatformBinaryName()`.

Author: BYK

.github/workflows/ci.yml

@@ -73,11 +73,13 @@ jobs:
             else
               # main, release/**, workflow_call: full cross-platform matrix
               echo '{"include":[
-                {"target":"darwin-arm64",  "os":"macos-latest",  "can-test":true},
-                {"target":"linux-x64",     "os":"ubuntu-latest", "can-test":true},
-                {"target":"windows-x64",   "os":"windows-latest","can-test":true},
-                {"target":"darwin-x64",    "os":"macos-latest",  "can-test":false},
-                {"target":"linux-arm64",   "os":"ubuntu-latest", "can-test":false}
+                {"target":"darwin-arm64",      "os":"macos-latest",  "can-test":true},
+                {"target":"linux-x64",         "os":"ubuntu-latest", "can-test":true},
+                {"target":"linux-x64-musl",    "os":"ubuntu-latest", "can-test":false},
+                {"target":"windows-x64",       "os":"windows-latest","can-test":true},
+                {"target":"darwin-x64",        "os":"macos-latest",  "can-test":false},
+                {"target":"linux-arm64",       "os":"ubuntu-latest", "can-test":false},
+                {"target":"linux-arm64-musl",  "os":"ubuntu-latest", "can-test":false}
               ]}'
             fi
             echo 'MATRIX_EOF'
@@ -265,6 +267,11 @@ jobs:
           else
             ./dist-bin/sentry-${{ matrix.target }} --help
           fi
+      - name: Smoke test (musl/Alpine)
+        if: matrix.target == 'linux-x64-musl'
+        run: |
+          docker run --rm -v "$PWD/dist-bin:/dist-bin:ro" alpine:latest \
+            /dist-bin/sentry-linux-x64-musl --help
       - name: Upload binary artifact
         uses: actions/upload-artifact@v7
         with:

install

@@ -51,7 +51,7 @@ report_error() {
     envelope=$(printf '%s\n%s\n%s' \
       "{\"event_id\":\"${event_id}\",\"dsn\":\"https://${SENTRY_DSN_KEY}@o1.ingest.us.sentry.io/${SENTRY_PROJECT_ID}\"}" \
       '{"type":"event"}' \
-      "{\"event_id\":\"${event_id}\",\"timestamp\":\"${timestamp}\",\"platform\":\"other\",\"level\":\"error\",\"logger\":\"install\",\"server_name\":\"install-script\",\"message\":{\"formatted\":\"${json_msg}\"},\"tags\":{\"os\":\"${os:-unknown}\",\"arch\":\"${arch:-unknown}\",\"channel\":\"${json_channel}\",\"step\":\"${json_step}\",\"install.version\":\"${json_version}\"},\"contexts\":{\"runtime\":{\"name\":\"bash\",\"version\":\"${BASH_VERSION:-unknown}\"}}}")
+      "{\"event_id\":\"${event_id}\",\"timestamp\":\"${timestamp}\",\"platform\":\"other\",\"level\":\"error\",\"logger\":\"install\",\"server_name\":\"install-script\",\"message\":{\"formatted\":\"${json_msg}\"},\"tags\":{\"os\":\"${os:-unknown}\",\"arch\":\"${arch:-unknown}\",\"libc\":\"${libc_variant:-glibc}\",\"channel\":\"${json_channel}\",\"step\":\"${json_step}\",\"install.version\":\"${json_version}\"},\"contexts\":{\"runtime\":{\"name\":\"bash\",\"version\":\"${BASH_VERSION:-unknown}\"}}}")
 
     curl -sf --max-time 2 \
       -H "Content-Type: application/x-sentry-envelope" \
@@ -143,6 +143,33 @@ case "$arch" in
   *) die "Unsupported architecture: $arch" "detect-arch" ;;
 esac
 
+# Detect C library variant (musl vs glibc) on Linux.
+# musl-based systems (Alpine, Void, etc.) need a different binary.
+libc_suffix=""
+if [[ "$os" == "linux" ]]; then
+  detect_musl() {
+    # Heuristic 1: Check for musl dynamic linker
+    local musl_arch
+    case "$arch" in
+      x64) musl_arch="x86_64" ;;
+      arm64) musl_arch="aarch64" ;;
+    esac
+    [ -f "/lib/ld-musl-${musl_arch}.so.1" ] && return 0
+
+    # Heuristic 2: ldd --version outputs "musl libc" on musl systems
+    if command -v ldd >/dev/null 2>&1; then
+      ldd --version 2>&1 | grep -qi musl && return 0
+    fi
+
+    return 1
+  }
+
+  if detect_musl; then
+    libc_suffix="-musl"
+    libc_variant="musl"
+  fi
+fi
+
 # Validate supported combinations
 suffix=""
 if [[ "$os" == "windows" ]]; then
@@ -199,7 +226,7 @@ if [[ "$requested_version" == "nightly" ]]; then
   # Each OCI layer has "digest" before "org.opencontainers.image.title".
   # Track the last-seen digest and print it when the target filename matches.
   # This avoids sed newline replacement which differs between GNU and BSD.
-  gz_filename="sentry-${os}-${arch}${suffix}.gz"
+  gz_filename="sentry-${os}-${arch}${libc_suffix}${suffix}.gz"
   digest=$(echo "$MANIFEST" \
     | awk -F'"' -v target="$gz_filename" '{
         for(i=1;i<=NF;i++){
@@ -238,7 +265,7 @@ else
 
   # Strip leading 'v' if present (releases use version without 'v' prefix)
   version="${version#v}"
-  filename="sentry-${os}-${arch}${suffix}"
+  filename="sentry-${os}-${arch}${libc_suffix}${suffix}"
   url="https://github.com/getsentry/cli/releases/download/${version}/${filename}"
 
   echo -e "${MUTED}Downloading sentry v${version}...${NC}"

script/build.ts

@@ -25,12 +25,14 @@
  *     sentry-darwin-arm64
  *     sentry-darwin-x64
  *     sentry-linux-arm64
+ *     sentry-linux-arm64-musl
  *     sentry-linux-x64
+ *     sentry-linux-x64-musl
  *     sentry-windows-x64.exe
  *     bin.js.map          (sourcemap, uploaded to Sentry then deleted)
  */
 
-import { mkdirSync, renameSync } from "node:fs";
+import { existsSync, mkdirSync, renameSync } from "node:fs";
 import { promisify } from "node:util";
 import { gzip } from "node:zlib";
 import { processBinary } from "binpunch";
@@ -51,25 +53,43 @@ const SENTRY_CLIENT_ID = process.env.SENTRY_CLIENT_ID ?? "";
 type BuildTarget = {
   os: "darwin" | "linux" | "win32";
   arch: "arm64" | "x64";
+  /** C library variant. Only relevant for Linux targets (musl for Alpine, etc.) */
+  libc?: "musl";
 };
 
 const ALL_TARGETS: BuildTarget[] = [
   { os: "darwin", arch: "arm64" },
   { os: "darwin", arch: "x64" },
   { os: "linux", arch: "arm64" },
+  { os: "linux", arch: "arm64", libc: "musl" },
   { os: "linux", arch: "x64" },
+  { os: "linux", arch: "x64", libc: "musl" },
   { os: "win32", arch: "x64" },
 ];
 
 /** Get package name for a target (uses "windows" instead of "win32") */
 function getPackageName(target: BuildTarget): string {
   const platformName = target.os === "win32" ? "windows" : target.os;
-  return `sentry-${platformName}-${target.arch}`;
+  const libcSuffix = target.libc ? `-${target.libc}` : "";
+  return `sentry-${platformName}-${target.arch}${libcSuffix}`;
+}
+
+/**
+ * Detect musl libc on the current system (for `--single` builds).
+ * Checks for the musl dynamic linker at the well-known path.
+ */
+function detectMusl(): boolean {
+  if (process.platform !== "linux") {
+    return false;
+  }
+  const muslArch = process.arch === "x64" ? "x86_64" : "aarch64";
+  return existsSync(`/lib/ld-musl-${muslArch}.so.1`);
 }
 
 /** Get Bun compile target string */
 function getBunTarget(target: BuildTarget): string {
-  return `bun-${target.os}-${target.arch}`;
+  const libcSuffix = target.libc ? `-${target.libc}` : "";
+  return `bun-${target.os}-${target.arch}${libcSuffix}`;
 }
 
 /** Path to the pre-bundled JS used by Step 2 (compile). */
@@ -278,7 +298,9 @@ async function compileTarget(target: BuildTarget): Promise<boolean> {
           | "bun-darwin-arm64"
           | "bun-darwin-x64"
           | "bun-linux-x64"
+          | "bun-linux-x64-musl"
           | "bun-linux-arm64"
+          | "bun-linux-arm64-musl"
           | "bun-windows-x64",
         outfile,
       },
@@ -331,16 +353,18 @@ async function compileTarget(target: BuildTarget): Promise<boolean> {
   return true;
 }
 
-/** Parse target string (e.g., "darwin-x64" or "linux-arm64") into BuildTarget */
+/** Parse target string (e.g., "darwin-x64", "linux-arm64", "linux-x64-musl") into BuildTarget */
 function parseTarget(targetStr: string): BuildTarget | null {
   // Handle "windows" alias for "win32"
   const normalized = targetStr.replace("windows-", "win32-");
-  const [os, arch] = normalized.split("-") as [
-    BuildTarget["os"],
-    BuildTarget["arch"],
-  ];
-
-  const target = ALL_TARGETS.find((t) => t.os === os && t.arch === arch);
+  const parts = normalized.split("-");
+  const os = parts[0] as BuildTarget["os"];
+  const arch = parts[1] as BuildTarget["arch"];
+  const libc = parts[2] === "musl" ? ("musl" as const) : undefined;
+
+  const target = ALL_TARGETS.find(
+    (t) => t.os === os && t.arch === arch && t.libc === libc
+  );
   return target ?? null;
 }
 
@@ -372,15 +396,19 @@ async function build(): Promise<void> {
     if (!target) {
       console.error(`Invalid target: ${targetArg}`);
       console.error(
-        `Valid targets: ${ALL_TARGETS.map((t) => `${t.os === "win32" ? "windows" : t.os}-${t.arch}`).join(", ")}`
+        `Valid targets: ${ALL_TARGETS.map((t) => `${t.os === "win32" ? "windows" : t.os}-${t.arch}${t.libc ? `-${t.libc}` : ""}`).join(", ")}`
       );
       process.exit(1);
     }
     targets = [target];
     console.log(`\nBuilding for target: ${getPackageName(target)}`);
   } else if (singleBuild) {
+    const musl = detectMusl();
     const currentTarget = ALL_TARGETS.find(
-      (t) => t.os === process.platform && t.arch === process.arch
+      (t) =>
+        t.os === process.platform &&
+        t.arch === process.arch &&
+        (musl ? t.libc === "musl" : !t.libc)
     );
     if (!currentTarget) {
       console.error(

src/lib/binary.ts

@@ -20,11 +20,58 @@ import { stringifyUnknown, UpgradeError } from "./errors.js";
 /** Known directories where the curl installer may place the binary */
 export const KNOWN_CURL_DIRS = [".local/bin", "bin", ".sentry/bin"];
 
+/**
+ * Detect whether the current process is running on a musl-based Linux system
+ * (e.g., Alpine Linux, Void Linux musl variant).
+ *
+ * Uses two heuristics in order of reliability:
+ * 1. Check for `/lib/ld-musl-<arch>.so.1` — the musl dynamic linker is always
+ *    at this path on musl systems. Fast stat check, no subprocess.
+ * 2. Parse `ldd --version` output — musl's ldd writes "musl libc" to stderr,
+ *    while glibc outputs "GNU C Library" to stdout.
+ *
+ * The result is cached after first call since libc cannot change at runtime.
+ */
+let cachedIsMusl: boolean | undefined;
+
+export function isMusl(): boolean {
+  if (process.platform !== "linux") {
+    return false;
+  }
+  if (cachedIsMusl !== undefined) {
+    return cachedIsMusl;
+  }
+
+  // Heuristic 1: Check for musl dynamic linker
+  const muslArch = process.arch === "x64" ? "x86_64" : "aarch64";
+  if (existsSync(`/lib/ld-musl-${muslArch}.so.1`)) {
+    cachedIsMusl = true;
+    return true;
+  }
+
+  // Heuristic 2: ldd --version output (musl ldd writes "musl libc" to stderr)
+  try {
+    const result = Bun.spawnSync(["ldd", "--version"], {
+      stdout: "pipe",
+      stderr: "pipe",
+    });
+    const output =
+      Buffer.from(result.stdout).toString() +
+      Buffer.from(result.stderr).toString();
+    cachedIsMusl = output.toLowerCase().includes("musl");
+    return cachedIsMusl;
+  } catch {
+    // ldd not found or failed — assume glibc (the common case)
+    cachedIsMusl = false;
+    return false;
+  }
+}
+
 /**
  * Build the platform-specific binary base name.
  *
  * Matches the naming convention used by GitHub Releases and GHCR:
- * `sentry-<os>-<arch>[.exe]` (e.g., `sentry-linux-x64`, `sentry-darwin-arm64`).
+ * `sentry-<os>-<arch>[-musl][.exe]` (e.g., `sentry-linux-x64`, `sentry-linux-arm64-musl`).
  */
 export function getPlatformBinaryName(): string {
   let os: string;
@@ -36,8 +83,9 @@ export function getPlatformBinaryName(): string {
     os = "linux";
   }
   const arch = process.arch === "arm64" ? "arm64" : "x64";
+  const libcSuffix = isMusl() ? "-musl" : "";
   const suffix = process.platform === "win32" ? ".exe" : "";
-  return `sentry-${os}-${arch}${suffix}`;
+  return `sentry-${os}-${arch}${libcSuffix}${suffix}`;
 }
 
 /**

src/lib/telemetry.ts

@@ -12,6 +12,7 @@
 import { chmodSync, statSync } from "node:fs";
 // biome-ignore lint/performance/noNamespaceImport: Sentry SDK recommends namespace import
 import * as Sentry from "@sentry/node-core/light";
+import { isMusl } from "./binary.js";
 import {
   CLI_VERSION,
   getCliEnvironment,
@@ -433,6 +434,19 @@ export function getSentryTracePropagationTargets(): (string | RegExp)[] {
  *
  * @internal Exported for testing
  */
+
+/**
+ * Set the cli.libc Sentry tag on Linux (musl for Alpine, glibc for most distros).
+ * No-op on non-Linux — the concept doesn't apply to macOS/Windows.
+ * Extracted from initSentry to stay under the cognitive complexity limit.
+ */
+function setLibcTag(): void {
+  if (process.platform !== "linux") {
+    return;
+  }
+  Sentry.setTag("cli.libc", isMusl() ? "musl" : "glibc");
+}
+
 export function initSentry(
   enabled: boolean,
   options?: { libraryMode?: boolean }
@@ -600,6 +614,9 @@ export function initSentry(
     // Tag whether running in an interactive terminal or agent/CI environment
     Sentry.setTag("is_tty", !!process.stdout.isTTY);
 
+    // Tag the C library variant on Linux (musl vs glibc).
+    setLibcTag();
+
     // Tag which AI agent (if any) is driving the CLI.
     // Env var detection is sync (instant). If no env var matches, fire off
     // async process tree detection in the background — it sets the tag

test/lib/binary.test.ts

@@ -22,8 +22,10 @@ import {
   getBinaryDownloadUrl,
   getBinaryFilename,
   getBinaryPaths,
+  getPlatformBinaryName,
   installBinary,
   isDowngrade,
+  isMusl,
   releaseLock,
   replaceBinarySync,
 } from "../../src/lib/binary.js";
@@ -523,3 +525,62 @@ describe("isDowngrade", () => {
     );
   });
 });
+
+describe("isMusl", () => {
+  test("returns false on non-Linux platforms", () => {
+    if (process.platform !== "linux") {
+      expect(isMusl()).toBe(false);
+    }
+  });
+
+  test("returns a boolean on Linux", () => {
+    if (process.platform === "linux") {
+      expect(typeof isMusl()).toBe("boolean");
+    }
+  });
+
+  test("result is cached (calling twice returns same value)", () => {
+    const first = isMusl();
+    const second = isMusl();
+    expect(first).toBe(second);
+  });
+});
+
+describe("getPlatformBinaryName", () => {
+  test("starts with sentry- prefix", () => {
+    expect(getPlatformBinaryName()).toStartWith("sentry-");
+  });
+
+  test("includes correct architecture", () => {
+    const name = getPlatformBinaryName();
+    const expectedArch = process.arch === "arm64" ? "arm64" : "x64";
+    expect(name).toContain(expectedArch);
+  });
+
+  test("includes correct OS", () => {
+    const name = getPlatformBinaryName();
+    if (process.platform === "darwin") {
+      expect(name).toContain("darwin");
+    } else if (process.platform === "win32") {
+      expect(name).toContain("windows");
+      expect(name).toEndWith(".exe");
+    } else {
+      expect(name).toContain("linux");
+    }
+  });
+
+  test("on CI (glibc), does not contain -musl suffix", () => {
+    // CI runners use glibc-based Ubuntu. This test verifies the
+    // musl detection correctly identifies glibc systems.
+    if (process.platform === "linux" && !isMusl()) {
+      expect(getPlatformBinaryName()).not.toContain("-musl");
+    }
+  });
+
+  test("includes -musl suffix on musl systems", () => {
+    // Only runs on musl-based systems (e.g., Alpine CI containers)
+    if (process.platform === "linux" && isMusl()) {
+      expect(getPlatformBinaryName()).toContain("-musl");
+    }
+  });
+});