Tutorial: integrar Sentry en el pipeline de deploy con GitHub Actions para subir source maps automáticamente y generar issues (PHP y JavaScript) — paso a paso

Ferramentas & Produtividade · Por Kevin Marcondes · Publicado el 30/10/2026 · 10 min de lectura

Este tutorial explica cómo integrar Sentry en el pipeline de deploy con GitHub Actions para subir automáticamente source maps y generar issues para PHP y JavaScript. Crearás releases en Sentry, enviarás los source maps desde el CI y versionarás frontend y backend en la misma release, garantizando stack traces legibles y correlación con los commits del deploy.

Prerequisitos y qué vas a configurar

Vas a crear un flujo de CI/CD que registre una release en Sentry, suba los source maps del frontend y marque la versión en el backend PHP. Al final, cualquier excepción en producción se convertirá en una issue en Sentry con stack trace desofuscado y asociada al commit del deploy.

Qué necesitas antes de empezar:

- Cuenta y proyecto en Sentry (organización y slug del proyecto).

- DSN de Sentry para frontend (público) y backend (servidor).

- Token de autenticación de Sentry con permiso para releases.

- Repositorio en GitHub con GitHub Actions habilitado.

- Proyecto JS que genere source maps (Vite o Webpack) y un backend PHP con el SDK de Sentry.

Si aún no tienes pipeline de deploy, consulta ideas de etapas en despliegue canario con GitHub Actions y cómo acelerar builds en runners efímeros en GitHub Actions. Para observabilidad de extremo a extremo en PHP, revisa observabilidad en PHP con Sentry.

Configurar Sentry en JavaScript y generar source maps en el build

Inicializa el SDK de Sentry en tu app JS y asegúrate de que el bundler genere source maps para producción. El source map es el archivo que mapea el JavaScript minificado al código fuente original, lo que permite stack traces legibles. La documentación de MDN explica el concepto en detalle.

Define las variables de release y environment provenientes del pipeline (por ejemplo, vía Vite). No publiques los .map en el CDN; los subiremos a Sentry desde el CI.

// Instale o SDK do browser
// npm i @sentry/browser --save

// src/sentry.ts (ou no bootstrap do app)
import * as Sentry from "@sentry/browser";

Sentry.init({
  dsn: import.meta.env.VITE_SENTRY_DSN, // DSN público do projeto
  release: import.meta.env.VITE_RELEASE, // versão injetada pelo CI
  environment: import.meta.env.MODE || "production",
});

// Exemplo: capturar erro manual (para teste)
// Sentry.captureException(new Error("Sentry JS test error"));

// vite.config.ts (Vite) — habilite sourcemap em produção
// import { defineConfig } from "vite";
// export default defineConfig({
//   build: { sourcemap: true },
// });

// webpack.config.js (Webpack) — alternativa
// module.exports = {
//   // ...
//   devtool: "source-map", // gera .map para produção
// };

PHP: instalar el SDK y marcar release/environment en el bootstrap

En el backend PHP, instala el SDK e inicializa con DSN, release y environment. Esto asegura que las excepciones del servidor se atribuyan a la misma release que el frontend. Los frameworks suelen tener integraciones propias; la base que sigue funciona en cualquier app PHP.

Para capturar excepciones no tratadas, puedes usar el handler por defecto del SDK o integrarlo con tu framework. Evita registrar tokens sensibles en los logs.

<?php
// Instale o SDK PHP (Composer):
// composer require sentry/sdk

require_once __DIR__ . '/vendor/autoload.php';

Sentry\init([
    'dsn' => getenv('SENTRY_DSN'),
    'release' => getenv('RELEASE') ?: getenv('SENTRY_RELEASE'),
    'environment' => getenv('ENVIRONMENT') ?: 'production',
]);

// Exemplo de teste
// try {
//     throw new Exception('Sentry PHP test error');
// } catch (Throwable $e) {
//     Sentry\captureException($e);
// }

Qué secretos y variables usar en GitHub Actions

Crea secrets en el repositorio para el token de Sentry y los slugs de organización/proyecto. Las variables de release y environment pueden definirse como env del workflow. Nunca expongas SENTRY_AUTH_TOKEN en los logs.

Workflow GitHub Actions: build, release y upload automático de source maps

El workflow siguiente crea una release en Sentry, asocia commits, sube los source maps generados por el bundler y finaliza la release. También inyecta RELEASE y el DSN público en el build del frontend para que los eventos lleguen con las marcas correctas.

Si tu deploy tiene etapas adicionales (canario, smoke tests, rollback), intégralo con tu pipeline existente. Ejemplos: despliegue canario y rollback y smoke tests.

name: deploy

on:
  push:
    branches: ["main"]

env:
  RELEASE: ${{ github.sha }}
  ENVIRONMENT: production

jobs:
  build-and-release:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0 # necessário para set-commits --auto

      - name: Setup Node
        uses: actions/setup-node@v4
        with:
          node-version: '20'

      - name: Install deps
        run: npm ci

      - name: Build (inject release and DSN)
        run: |
          echo "VITE_RELEASE=${RELEASE}" >> .env
          echo "VITE_SENTRY_DSN=${{ secrets.SENTRY_DSN_PUBLIC }}" >> .env
          npm run build

      - name: Install sentry-cli
        run: npm i -g @sentry/cli

      - name: Create release in Sentry
        env:
          SENTRY_AUTH_TOKEN: ${{ secrets.SENTRY_AUTH_TOKEN }}
          SENTRY_ORG: ${{ secrets.SENTRY_ORG }}
          SENTRY_PROJECT: ${{ secrets.SENTRY_PROJECT }}
        run: |
          sentry-cli releases new "$RELEASE"
          sentry-cli releases set-commits "$RELEASE" --auto

      - name: Upload source maps to Sentry
        env:
          SENTRY_AUTH_TOKEN: ${{ secrets.SENTRY_AUTH_TOKEN }}
          SENTRY_ORG: ${{ secrets.SENTRY_ORG }}
          SENTRY_PROJECT: ${{ secrets.SENTRY_PROJECT }}
        run: |
          # Ajuste o caminho conforme seu bundler (ex.: dist, build)
          sentry-cli releases files "$RELEASE" upload-sourcemaps ./dist \
            --url-prefix "~/" \
            --validate --rewrite

      - name: Finalize release
        env:
          SENTRY_AUTH_TOKEN: ${{ secrets.SENTRY_AUTH_TOKEN }}
          SENTRY_ORG: ${{ secrets.SENTRY_ORG }}
          SENTRY_PROJECT: ${{ secrets.SENTRY_PROJECT }}
        run: sentry-cli releases finalize "$RELEASE"

      - name: Deploy
        run: |
          # Execute seu deploy (ex.: rsync, kubectl, serverless, etc.)
          echo "Deploy step here"

Cómo marcar la misma release en el backend PHP durante el deploy

El backend debe recibir la misma variable RELEASE y ENVIRONMENT usadas en el workflow. Puedes publicar esas variables en el .env del servidor, en el manifiesto del contenedor o en el gestor de servicios (ej.: systemd, ECS). PHP leerá esos valores en el bootstrap para enviar eventos a Sentry con la versión correcta.

• Guarda RELEASE y ENVIRONMENT en la configuración del servicio.
• Reinicia el proceso PHP/FPM tras cambiar variables.
• Asegura que el DSN del servidor (SENTRY_DSN) esté configurado en el host, contenedor o secret manager.

# Exemplo simples: escrever variáveis em um .env no servidor durante o deploy
# (substitua /var/www/app pelo caminho do seu app)
ssh user@host "echo 'RELEASE=${RELEASE}' | sudo tee -a /var/www/app/.env && \
               echo 'ENVIRONMENT=${ENVIRONMENT}' | sudo tee -a /var/www/app/.env && \
               sudo systemctl restart php-fpm"

Cómo confirmar que funcionó (verificación post-deploy)

Valida la integración generando una excepción de prueba en frontend y backend. En pocos segundos Sentry debería crear issues con la release y el environment correctos, y el stack trace JS debería aparecer desofuscado gracias a los source maps.

Realiza la prueba solo en un entorno controlado y elimina el código de prueba después de validar.

• Verifica en Sentry que los eventos están en la release correcta.
• Confirma que el stack trace JS apunta a archivos/líneas originales.
• Comprueba que el environment corresponde a production o staging.

# Frontend (abra o console do navegador após o deploy)
// window.Sentry.captureException(new Error("Sentry JS test after deploy"));

# Backend PHP (rota temporária)
<?php
// /debug/sentry-test (remova depois)
throw new Exception('Sentry PHP test after deploy');

Solución de problemas comunes

Eventos llegan sin release? Asegúrate de que la variable RELEASE fue inyectada en el build del frontend y está disponible en el bootstrap PHP. El valor debe ser idéntico al usado por sentry-cli releases.

Los source maps no aplican? El url-prefix debe coincidir con lo que la app sirve en producción. Si tus assets viven bajo /static o en un CDN, ajusta el prefijo. Nunca publiques los .map públicamente; mantenlos privados y súbelos solo a Sentry.

Token inválido o sin permisos? Recrée SENTRY_AUTH_TOKEN con scopes de releases en Sentry. No registres el token en logs. Usa GitHub Secrets.

El build borra los .map? Confirma la configuración del bundler (Vite: build.sourcemap=true; Webpack: devtool=source-map). MDN tiene una guía sobre source maps.

Commits no aparecen en la release? Verifica que el repositorio se haya hecho checkout con historial completo (fetch-depth: 0) antes de set-commits, o proporciona el rango manualmente a sentry-cli. En monorepos, indica el project correcto.

Preguntas frecuentes

¿Necesito exponer el DSN en el frontend?

Sí, el SDK del navegador usa un DSN público para enviar eventos. Ese DSN no otorga acceso administrativo. El DSN del servidor (backend) debe permanecer protegido como secreto. Nunca expongas SENTRY_AUTH_TOKEN; ese token se usa solo en el CI para releases y upload de source maps.

¿Cómo definir la versión (release) automáticamente en el CI?

Usa una versión derivada del repositorio, como GITHUB_SHA, una tag semántica o un hash corto. Lo importante es usar el mismo valor en sentry-cli releases, en el build del frontend y en la configuración del backend para que los eventos se asignen correctamente a la misma release.

¿Dónde deben residir los source maps: en Sentry o en el CDN?

Para que Sentry muestre stack traces desofuscados basta con subir los source maps al propio Sentry desde CI/CD. No es necesario publicarlos en la CDN. Mantener los .map privados evita exponer código fuente. Solo asegúrate de que url-prefix y paths coincidan con los assets servidos en producción.

¿Qué permisos necesita el token de Sentry para el upload?

El token (SENTRY_AUTH_TOKEN) debe poder crear y editar releases y subir archivos. Créalo en Sentry con los scopes apropiados para el proyecto y guárdalo en GitHub Secrets. Restringe el alcance por organización/proyecto y revoca tokens antiguos periódicamente.

¿Puedo usar la action oficial en lugar de sentry-cli vía npm?

Sí. Puedes usar una action dedicada para releases de Sentry. Simplifica set-commits, upload de source maps y finalize. El flujo de variables y secretos es el mismo. Prefiere esta opción si quieres menos pasos de shell en el workflow.

¿Funciona con monorepos y múltiples proyectos en Sentry?

Funciona, pero debes ejecutar sentry-cli para cada proyecto en el que quieras publicar la release y los source maps, usando el SENTRY_PROJECT correcto. Ajusta los directorios de build por app y define releases consistentes entre servicios para mantener la correlación entre frontend y backends.

Ver también

• Tutorial: configurar mTLS entre Traefik y servicios en Docker Compose usando smallstep CA y certificados automáticos — paso a paso
• Configurar retención y compresión de logs de contenedores Docker con journald + logrotate + rsyslog en VPS con poco disco
• Tutorial: configurar GitHub Actions para tests de integración con PostgreSQL en contenedores efímeros y rollback automático de migrations — guía práctica
• Configurar BuildKit garbage collection y systemd timers para limpieza automática de imágenes y volúmenes Docker en VPS: tutorial práctico