EAS Build Hooks

CHANGELOG.md

@@ -13,6 +13,22 @@
 - Fix AGP Artifacts API conflict caused by eager task realization in `sentry.gradle` ([#5714](https://github.com/getsentry/sentry-react-native/pull/5714))
 - Fix Android crash on app launch caused by version mismatch between Sentry Android SDK and Sentry Android Gradle Plugin ([#5726](https://github.com/getsentry/sentry-react-native/pull/5726))
 
+### Features
+
+- EAS Build Hooks ([#5666](https://github.com/getsentry/sentry-react-native/pull/5666))
+
+  - Capture EAS build events in Sentry. Add the following to your `package.json`:
+
+    ```json
+    {
+      "scripts": {
+        "eas-build-on-complete": "sentry-eas-build-on-complete"
+      }
+    }
+    ```
+
+    Set `SENTRY_DSN` in your EAS secrets, and optionally `SENTRY_EAS_BUILD_CAPTURE_SUCCESS=true` to also capture successful builds.
+
 ### Dependencies
 
 - Bump Android SDK from v8.32.0 to v8.33.0 ([#5684](https://github.com/getsentry/sentry-react-native/pull/5684))

packages/core/package.json

@@ -45,6 +45,9 @@
     "lint:prettier": "prettier  --config ../../.prettierrc.json --ignore-path ../../.prettierignore --check \"{src,test,scripts,plugin/src}/**/**.ts\""
   },
   "bin": {
+    "sentry-eas-build-on-complete": "scripts/eas/build-on-complete.js",
+    "sentry-eas-build-on-error": "scripts/eas/build-on-error.js",
+    "sentry-eas-build-on-success": "scripts/eas/build-on-success.js",
     "sentry-expo-upload-sourcemaps": "scripts/expo-upload-sourcemaps.js"
   },
   "keywords": [

packages/core/scripts/eas/build-on-complete.js

@@ -0,0 +1,53 @@
+#!/usr/bin/env node
+/**
+ * EAS Build Hook: on-complete
+ *
+ * This script captures EAS build completion events and reports them to Sentry.
+ * It uses the EAS_BUILD_STATUS environment variable to determine whether
+ * the build succeeded or failed.
+ *
+ * Add it to your package.json scripts:
+ *
+ *   "eas-build-on-complete": "sentry-eas-build-on-complete"
+ *
+ * NOTE: Use EITHER this hook OR the separate on-error/on-success hooks, not both.
+ * Using both will result in duplicate events being sent to Sentry.
+ *
+ * Required environment variables:
+ *   - SENTRY_DSN: Your Sentry DSN
+ *
+ * Optional environment variables:
+ *   - SENTRY_EAS_BUILD_CAPTURE_SUCCESS: Set to 'true' to also capture successful builds
+ *   - SENTRY_EAS_BUILD_TAGS: JSON string of additional tags
+ *   - SENTRY_EAS_BUILD_ERROR_MESSAGE: Custom error message for failed builds
+ *   - SENTRY_EAS_BUILD_SUCCESS_MESSAGE: Custom success message for successful builds
+ *
+ * EAS Build provides:
+ *   - EAS_BUILD_STATUS: 'finished' or 'errored'
+ *
+ * @see https://docs.expo.dev/build-reference/npm-hooks/
+ * @see https://docs.sentry.io/platforms/react-native/
+ *
+ */
+
+const { loadEnv, loadHooksModule, parseBaseOptions, runHook } = require('./utils');
+
+async function main() {
+  loadEnv();
+
+  const hooks = loadHooksModule();
+  const options = {
+    ...parseBaseOptions(),
+    errorMessage: process.env.SENTRY_EAS_BUILD_ERROR_MESSAGE,
+    successMessage: process.env.SENTRY_EAS_BUILD_SUCCESS_MESSAGE,
+    captureSuccessfulBuilds: process.env.SENTRY_EAS_BUILD_CAPTURE_SUCCESS === 'true',
+  };
+
+  await runHook('on-complete', () => hooks.captureEASBuildComplete(options));
+}
+
+main().catch(error => {
+  // eslint-disable-next-line no-console
+  console.error('[Sentry] Unexpected error in eas-build-on-complete hook:', error);
+  process.exit(1);
+});

packages/core/scripts/eas/build-on-error.js

@@ -0,0 +1,42 @@
+#!/usr/bin/env node
+/**
+ * EAS Build Hook: on-error
+ *
+ * This script captures EAS build failures and reports them to Sentry.
+ * Add it to your package.json scripts:
+ *
+ *   "eas-build-on-error": "sentry-eas-build-on-error"
+ *
+ * NOTE: Use EITHER this hook (with on-success) OR the on-complete hook, not both.
+ * Using both will result in duplicate events being sent to Sentry.
+ *
+ * Required environment variables:
+ *   - SENTRY_DSN: Your Sentry DSN
+ *
+ * Optional environment variables:
+ *   - SENTRY_EAS_BUILD_TAGS: JSON string of additional tags
+ *   - SENTRY_EAS_BUILD_ERROR_MESSAGE: Custom error message
+ *
+ * @see https://docs.expo.dev/build-reference/npm-hooks/
+ * @see https://docs.sentry.io/platforms/react-native/
+ */
+
+const { loadEnv, loadHooksModule, parseBaseOptions, runHook } = require('./utils');
+
+async function main() {
+  loadEnv();
+
+  const hooks = loadHooksModule();
+  const options = {
+    ...parseBaseOptions(),
+    errorMessage: process.env.SENTRY_EAS_BUILD_ERROR_MESSAGE,
+  };
+
+  await runHook('on-error', () => hooks.captureEASBuildError(options));
+}
+
+main().catch(error => {
+  // eslint-disable-next-line no-console
+  console.error('[Sentry] Unexpected error in eas-build-on-error hook:', error);
+  process.exit(1);
+});

packages/core/scripts/eas/build-on-success.js

@@ -0,0 +1,44 @@
+#!/usr/bin/env node
+/**
+ * EAS Build Hook: on-success
+ *
+ * This script captures EAS build successes and reports them to Sentry.
+ * Add it to your package.json scripts:
+ *
+ *   "eas-build-on-success": "sentry-eas-build-on-success"
+ *
+ * NOTE: Use EITHER this hook (with on-error) OR the on-complete hook, not both.
+ * Using both will result in duplicate events being sent to Sentry.
+ *
+ * Required environment variables:
+ *   - SENTRY_DSN: Your Sentry DSN
+ *   - SENTRY_EAS_BUILD_CAPTURE_SUCCESS: Set to 'true' to capture successful builds
+ *
+ * Optional environment variables:
+ *   - SENTRY_EAS_BUILD_TAGS: JSON string of additional tags
+ *   - SENTRY_EAS_BUILD_SUCCESS_MESSAGE: Custom success message
+ *
+ * @see https://docs.expo.dev/build-reference/npm-hooks/
+ * @see https://docs.sentry.io/platforms/react-native/
+ */
+
+const { loadEnv, loadHooksModule, parseBaseOptions, runHook } = require('./utils');
+
+async function main() {
+  loadEnv();
+
+  const hooks = loadHooksModule();
+  const options = {
+    ...parseBaseOptions(),
+    successMessage: process.env.SENTRY_EAS_BUILD_SUCCESS_MESSAGE,
+    captureSuccessfulBuilds: process.env.SENTRY_EAS_BUILD_CAPTURE_SUCCESS === 'true',
+  };
+
+  await runHook('on-success', () => hooks.captureEASBuildSuccess(options));
+}
+
+main().catch(error => {
+  // eslint-disable-next-line no-console
+  console.error('[Sentry] Unexpected error in eas-build-on-success hook:', error);
+  process.exit(1);
+});

packages/core/scripts/eas/utils.js

@@ -0,0 +1,124 @@
+/**
+ * Shared utilities for EAS Build Hook scripts.
+ *
+ * @see https://docs.expo.dev/build-reference/npm-hooks/
+ */
+
+/* eslint-disable no-console */
+
+const path = require('path');
+const fs = require('fs');
+
+/**
+ * Merges parsed env vars into process.env without overwriting existing values.
+ * This preserves EAS secrets and other pre-set environment variables.
+ * @param {object} parsed - Parsed environment variables from dotenv
+ */
+function mergeEnvWithoutOverwrite(parsed) {
+  for (const key of Object.keys(parsed)) {
+    if (process.env[key] === undefined) {
+      process.env[key] = parsed[key];
+    }
+  }
+}
+
+/**
+ * Loads environment variables from various sources:
+ * - @expo/env (if available)
+ * - .env file (via dotenv, if available)
+ * - .env.sentry-build-plugin file
+ *
+ * NOTE: Existing environment variables (like EAS secrets) are NOT overwritten.
+ */
+function loadEnv() {
+  // Try @expo/env first
+  try {
+    require('@expo/env').load('.');
+  } catch (_e) {
+    // Fallback to dotenv if available
+    try {
+      const dotenvPath = path.join(process.cwd(), '.env');
+      if (fs.existsSync(dotenvPath)) {
+        const dotenvFile = fs.readFileSync(dotenvPath, 'utf-8');
+        const dotenv = require('dotenv');
+        mergeEnvWithoutOverwrite(dotenv.parse(dotenvFile));
+      }
+    } catch (_e2) {
+      // No dotenv available, continue with existing env vars
+    }
+  }
+
+  // Also load .env.sentry-build-plugin if it exists
+  try {
+    const sentryEnvPath = path.join(process.cwd(), '.env.sentry-build-plugin');
+    if (fs.existsSync(sentryEnvPath)) {
+      const dotenvFile = fs.readFileSync(sentryEnvPath, 'utf-8');
+      const dotenv = require('dotenv');
+      mergeEnvWithoutOverwrite(dotenv.parse(dotenvFile));
+    }
+  } catch (_e) {
+    // Continue without .env.sentry-build-plugin
+  }
+}
+
+/**
+ * Loads the EAS build hooks module from the compiled output.
+ * @returns {object} The hooks module exports
+ * @throws {Error} If the module cannot be loaded
+ */
+function loadHooksModule() {
+  try {
+    return require('../../dist/js/tools/easBuildHooks.js');
+  } catch (_e) {
+    console.error('[Sentry] Could not load EAS build hooks module. Make sure @sentry/react-native is properly installed.');
+    process.exit(1);
+  }
+}
+
+/**
+ * Parses common options from environment variables.
+ * @returns {object} Parsed options object
+ */
+function parseBaseOptions() {
+  const options = {
+    dsn: process.env.SENTRY_DSN,
+  };
+
+  // Parse additional tags if provided
+  if (process.env.SENTRY_EAS_BUILD_TAGS) {
+    try {
+      const parsed = JSON.parse(process.env.SENTRY_EAS_BUILD_TAGS);
+      if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
+        options.tags = parsed;
+      } else {
+        console.warn('[Sentry] SENTRY_EAS_BUILD_TAGS must be a JSON object (e.g., {"key":"value"}). Ignoring.');
+      }
+    } catch (_e) {
+      console.warn('[Sentry] Could not parse SENTRY_EAS_BUILD_TAGS as JSON. Ignoring.');
+    }
+  }
+
+  return options;
+}
+
+/**
+ * Wraps an async hook function with error handling.
+ * @param {string} hookName - Name of the hook for logging
+ * @param {Function} hookFn - Async function to execute
+ */
+async function runHook(hookName, hookFn) {
+  try {
+    await hookFn();
+    console.log(`[Sentry] EAS build ${hookName} hook completed.`);
+  } catch (error) {
+    console.error(`[Sentry] Error in eas-build-${hookName} hook:`, error);
+    // Don't fail the build hook itself
+  }
+}
+
+module.exports = {
+  loadEnv,
+  loadHooksModule,
+  parseBaseOptions,
+  runHook,
+};