Tutorial: integrar Sentry ao pipeline de deploy com GitHub Actions para upload automático de source maps e criação de issues (PHP e JavaScript) — passo a passo

Ferramentas & Produtividade · Por Kevin Marcondes · Publicado em 30/10/2026 · 10 min de leitura

Este tutorial ensina como integrar Sentry ao pipeline de deploy com GitHub Actions para upload automático de source maps e criação de issues (PHP e JavaScript). Você vai criar releases, enviar source maps no CI e versionar frontend e backend na mesma release, garantindo stack traces legíveis e correlação com commits do deploy.

Pré-requisitos e o que você vai configurar

Você vai criar um fluxo de CI/CD que registra uma release no Sentry, envia source maps do frontend e marca a versão no backend PHP. Ao final, qualquer exceção em produção vira uma issue no Sentry com stack trace desofuscado e associada ao commit do deploy.

O que você precisa antes de começar:

- Conta e projeto no Sentry (org e project slug).

- DSN do Sentry para o frontend (público) e backend (servidor).

- Token de autenticação do Sentry com permissão de releases.

- Repositório no GitHub com GitHub Actions habilitado.

- Projeto JS que gere source maps (Vite ou Webpack) e um backend PHP com Sentry SDK.

Se você ainda não tem pipeline de deploy, veja ideias de etapas em deploy canário com GitHub Actions e como acelerar builds em runners efêmeros no GitHub Actions. Para observabilidade de ponta a ponta em PHP, confira observabilidade em PHP com Sentry.

Configurar Sentry no JavaScript e gerar source maps do build

Inicialize o SDK do Sentry no seu app JS e garanta que o bundler gere source maps de produção. O source map é o arquivo que mapeia o JavaScript minificado para o código-fonte original, permitindo stack traces legíveis. A documentação da MDN explica o conceito de forma detalhada.

Defina as variáveis de release e environment vindas do pipeline (por exemplo, via Vite). Não publique os .map no CDN; vamos enviar os arquivos para o Sentry no 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 SDK e marcar release/env no bootstrap

No backend PHP, instale o SDK e inicialize com DSN, release e environment. Isso garante que exceções do servidor sejam atribuídas à mesma release do frontend. Frameworks podem ter integrações próprias; a base abaixo funciona em qualquer app PHP.

Para capturar exceções não tratadas, você pode usar o handler padrão do SDK ou integrar ao seu framework. Evite logar tokens sensíveis nas exceções.

<?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);
// }

Quais segredos e variáveis usar no GitHub Actions?

Crie segredos no repositório para o token do Sentry e slugs de organização/projeto. Variáveis de release e environment podem ser definidas como env do workflow. Nunca exponha o SENTRY_AUTH_TOKEN em logs.

Pipeline GitHub Actions: build, release e upload automático de source maps

O workflow abaixo cria uma release no Sentry, associa commits, envia source maps gerados pelo bundler e finaliza a release. Ele também injeta RELEASE e DSN público no build do frontend para que os eventos cheguem marcados corretamente.

Se seu deploy tiver etapas adicionais (canário, smoke tests, rollback), integre com seu pipeline existente. Exemplos: deploy canário e pipeline com rollback e 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"

Como marcar a mesma release no backend PHP durante o deploy?

O backend precisa receber a mesma variável RELEASE e ENVIRONMENT usadas no workflow. Você pode publicar essas variáveis no .env do servidor, no manifest do container ou no service manager (ex.: systemd, ECS). O PHP lerá esses valores no bootstrap para enviar eventos ao Sentry com a versão correta.

• Grave RELEASE e ENVIRONMENT na configuração do serviço.
• Reinicie o processo PHP/FPM após alterar variáveis.
• Garanta que o DSN do servidor (SENTRY_DSN) esteja configurado no host, container ou 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"

Como confirmar que funcionou (verificação pós-deploy)?

Valide a integração gerando uma exceção de teste no frontend e no backend. Em poucos segundos, o Sentry deve criar issues com a release e o environment corretos, e o stack trace do JS deve aparecer desofuscado graças aos source maps.

Faça o teste apenas em ambiente controlado e remova o código após validar.

• Verifique no Sentry que os eventos estão na release correta.
• Confirme que o stack trace JS aponta para arquivos/linhas originais.
• Cheque que o environment corresponde ao production ou 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');

Solução de problemas comuns

Eventos chegam sem release? Garanta que a variável RELEASE foi injetada no build do frontend e está disponível no bootstrap PHP. O valor precisa ser idêntico ao usado no sentry-cli releases.

Source maps não aplicam? O caminho (url-prefix) deve corresponder ao que o app serve em produção. Se seus assets vivem sob /static ou CDN, ajuste o prefixo. Nunca publique .map publicamente; mantenha-os privados e envie só ao Sentry.

Token inválido ou sem permissão? Recrie o SENTRY_AUTH_TOKEN com escopos de releases no Sentry. Não grave o token em logs. Use GitHub Secrets.

Build remove os .map? Confirme a configuração do bundler (Vite: build.sourcemap=true; Webpack: devtool=source-map). A documentação da MDN tem um guia sobre source maps.

Commits não aparecem na release? Verifique se o repositório foi checado com histórico completo (fetch-depth: 0) antes de set-commits, ou forneça o range manual ao sentry-cli. Em monorepo, informe project corretamente.

Perguntas frequentes

Preciso expor o DSN no frontend?

Sim, o SDK do navegador usa um DSN público para enviar eventos. Esse DSN não dá acesso administrativo. O DSN do servidor (backend) deve ficar protegido como secret. Nunca exponha o SENTRY_AUTH_TOKEN, que é usado apenas no CI para releases e upload de source maps.

Como definir a versão (release) automaticamente no CI?

Use uma versão derivada do repositório, como GITHUB_SHA, um tag semântico ou um hash curto. O importante é usar o mesmo valor no sentry-cli releases, no build do frontend e na configuração do backend para que os eventos sejam atribuídos corretamente à mesma release.

Onde ficam os source maps: Sentry ou CDN?

Para o Sentry funcionar, basta enviar os source maps para o Sentry via CI/CD. Eles não precisam ficar públicos na CDN. Manter .map privados evita expor código-fonte. Garanta apenas que url-prefix e paths correspondam aos assets produzidos e servidos em produção.

Quais permissões o token do Sentry precisa para o upload?

O token (SENTRY_AUTH_TOKEN) deve permitir criar e editar releases e fazer upload de arquivos. Crie-o no Sentry com escopos apropriados ao projeto e armazene em GitHub Secrets. Restrinja o escopo por organização/projeto e revogue tokens antigos periodicamente.

Posso usar a action oficial em vez do sentry-cli via npm?

Sim. Você pode usar uma action dedicada para releases do Sentry. Ela simplifica o set-commits, upload de source maps e finalize. O fluxo de variáveis e segredos permanece o mesmo. Prefira essa opção se quiser menos etapas de shell no workflow.

Funciona com monorepos e múltiplos projetos no Sentry?

Funciona, mas você deve executar sentry-cli para cada projeto no qual deseja publicar a release e os source maps, informando SENTRY_PROJECT correto. Ajuste diretórios de build por app e defina releases consistentes entre os serviços para manter a correlação entre frontend e backends.

Veja também

• tutorial: configurar mTLS entre Traefik e serviços em Docker Compose usando smallstep CA e certificados automáticos — passo a passo
• Configurar retenção e compactação de logs de containers Docker com journald + logrotate + rsyslog em VPS com pouco disco
• tutorial: configurar GitHub Actions para testes de integração com PostgreSQL em containers efêmeros e rollback automático de migrações — guia prático
• Configurar BuildKit garbage collection e systemd timers para limpeza automática de imagens e volumes Docker em VPS: tutorial prático