Anotações Automáticas no GA4: Conectando Seus Deploys via GitHub Actions

Uma das grandes dores de equipes de marketing e analytics é entender como as mudanças no site impactam as métricas de desempenho. Quando há um pico ou queda nos dados, é comum perguntar: "O que mudou no site nesse dia?".

Com o recente lançamento das anotações no Google Analytics 20 em março de 2025 e a subsequente identificação da API que permite automatizar sua criação, temos agora uma oportunidade de resolver este problema de forma elegante. Neste artigo, vamos explorar como criar anotações automáticas no Google Analytics 4 (GA4) toda vez que um código é enviado para a branch principal do seu repositório GitHub.

O que são Anotações no Google Analytics 4?

O Google Analytics 4 disponibilizou o recurso de anotações de dados em 20 de março de 2025. Mais recentemente, a API para criar estas anotações programaticamente foi identificada e disponibilizada, ampliando as possibilidades de automação.

Estas anotações aparecem como marcadores nos relatórios, permitindo contextualizar eventos importantes como:

• Lançamentos de campanhas
• Atualizações no site
• Mudanças técnicas
• Problemas identificados
• Eventos sazonais

As anotações ajudam a correlacionar mudanças nos dados com eventos específicos, facilitando a análise e comunicação entre equipes. Para entender melhor o contexto do GA4 como um todo, você pode conferir nosso guia completo sobre o Google Analytics 4.

Por que Automatizar Anotações de Deploy?

Automatizar a criação de anotações para cada deploy traz diversos benefícios:

1. Visibilidade imediata: As equipes de marketing e análise podem ver exatamente quando ocorreram mudanças no site
2. Correlação de dados: Facilita identificar se alterações de código impactaram métricas de desempenho, o que é especialmente útil para análises de SEO no GA4
3. Comunicação entre equipes: Diminui a necessidade de comunicação manual entre desenvolvedores e analistas
4. Documentação histórica: Cria um registro histórico de todas as alterações significativas no site
5. Diagnóstico mais rápido: Agiliza a investigação de problemas após lançamentos, complementando bem os relatórios para medir desempenho de SEO

O que vamos construir

Neste tutorial, você aprenderá a configurar uma integração que:

1. Detecta quando há um push para a branch main do seu repositório
2. Captura informações sobre o commit (hash, mensagem, etc.)
3. Cria automaticamente uma anotação no Google Analytics 4
4. Registra essas informações de forma visível nos relatórios do GA4

O que é GitHub Actions?

Para os profissionais de marketing e analytics que não estão familiarizados com ferramentas de desenvolvimento, o GitHub Actions é uma plataforma de automação integrada ao GitHub (o serviço mais popular para armazenar e gerenciar código). Com o GitHub Actions, é possível criar fluxos automatizados que são executados quando determinados eventos acontecem no repositório.

Em termos simples, o GitHub Actions funciona como um assistente que monitora seu repositório e executa tarefas específicas automaticamente quando algo acontece - neste caso, quando uma nova versão do código é enviada para o repositório. É como ter um sistema que diz: "Sempre que o time de desenvolvimento atualizar o site, registre isso automaticamente no Google Analytics."

Esta ferramenta elimina a necessidade de processos manuais, garantindo que cada mudança no código seja devidamente documentada nas ferramentas de análise, sem que alguém precise fazer isso manualmente.

Pré-requisitos

Para implementar esta solução, você precisará:

• Uma conta no GitHub com acesso a um repositório
• Uma propriedade no Google Analytics 4
• Uma conta no Google Cloud Platform
• Permissões para configurar secrets no GitHub
• Permissões para criar contas de serviço no Google Cloud

Passo a Passo da Implementação

1. Criar uma Conta de Serviço no Google Cloud

Primeiro, precisamos criar uma conta de serviço que terá permissões para acessar a API do GA4:

1. Acesse o Console do Google Cloud
2. Navegue até "IAM & Admin" > "Service Accounts"
3. Clique em "Create Service Account"
4. Dê um nome descritivo (ex: "ga4-annotations")
5. Atribua o papel "Analytics Admin" à conta
6. Crie uma chave JSON para a conta de serviço e faça o download

2. Adicionar a Conta de Serviço ao GA4

1. Acesse o Google Analytics
2. Vá para Admin > Propriedade > Gerenciamento de acesso
3. Clique em "+" para adicionar um usuário
4. Insira o email da conta de serviço (encontrado no arquivo JSON)
5. Atribua a permissão de "Editor"

3. Configurar Secrets no GitHub

1. Acesse seu repositório no GitHub
2. Vá para "Settings" > "Secrets and variables" > "Actions"
3. Adicione dois secrets:

   • GOOGLE_APPLICATION_CREDENTIALS_JSON

     : O conteúdo completo do arquivo JSON da conta de serviço

   • GA4_PROPERTY_ID

     : O ID da sua propriedade GA4 (um número como "123456789")

4. Código da Implementação

Em vez de fornecer os blocos de código diretamente aqui, você pode acessar a implementação completa no repositório público:

GitHub: deploy-annotations-to-ga4

O repositório contém:

1. Arquivo de workflow do GitHub Actions (

   .github/workflows/ga-annotations.yml

   )
   • Configura o ambiente e executa o script quando há um push para main
2. Script de criação de anotações (

   .github/scripts/create-annotation.js

   )
   • Lida com a autenticação com o Google Cloud
   • Formata os dados do commit para a anotação
   • Faz a chamada à API do GA4

Como funciona a integração

Vamos entender como funciona o fluxo completo da integração:

1. Acionador: Quando alguém faz push para a branch main, o GitHub Actions é acionado
2. Checkout: O código é baixado para o ambiente de execução
3. Ambiente: O Node.js é configurado e as dependências são instaladas
4. Autenticação: O script gera um JWT usando a chave privada da conta de serviço
5. Token: O JWT é trocado por um token de acesso OAuth
6. Informações: O script coleta dados sobre o commit (SHA, mensagem, autor)
7. Anotação: Uma requisição REST é feita para a API do GA4 para criar a anotação
8. Confirmação: O status da operação é registrado nos logs do GitHub Actions

Detalhes Técnicos

API de Anotações do GA4

A API de Anotações de Dados de Relatórios é um recurso relativamente novo do Google Analytics 4, disponível através da Google Analytics Admin API v1alpha. Uma anotação consiste em:

• Título: Nome legível da anotação
• Descrição: Detalhes sobre o evento
• Cor: Identificação visual (BLUE, GREEN, RED, etc.)
• Data: Data específica ou intervalo de datas

Autenticação com Google Cloud

O processo de autenticação envolve dois passos:

1. Geração de JWT: Usamos a biblioteca jsonwebtoken para criar um token JWT assinado com a chave privada da conta de serviço
2. Obtenção de Token de Acesso: Trocamos o JWT por um token OAuth 2.0 de acesso temporário

Variáveis de Ambiente do GitHub Actions

O GitHub Actions fornece várias variáveis de ambiente úteis, incluindo:

• GITHUB_SHA: O hash do commit que acionou o workflow
• GITHUB_REPOSITORY: O nome do repositório no formato "dono/nome"
• GITHUB_ACTOR: O usuário que iniciou o evento

Visualizando as Anotações

Depois de implementar esta solução, você poderá ver as anotações de deploy nos relatórios do GA4:

1. Acesse o Google Analytics 4
2. Navegue para qualquer relatório de dados ao longo do tempo
3. As anotações aparecerão como pequenos marcadores no gráfico
4. Passe o mouse sobre eles para ver os detalhes do deploy

Considerações de Segurança

É importante seguir as melhores práticas de segurança:

1. Princípio do privilégio mínimo: A conta de serviço deve ter apenas as permissões necessárias
2. Armazenamento seguro de credenciais: Use secrets do GitHub para proteger informações sensíveis
3. Rotação de chaves: Considere rotacionar periodicamente a chave da conta de serviço
4. Monitoramento: Acompanhe o uso da API para detectar atividades suspeitas

A integração do GitHub com o Google Analytics 4 para criar anotações automáticas de deploy oferece uma maneira eficiente de conectar o ciclo de desenvolvimento com a análise de dados. Isso ajuda as equipes a entender melhor o impacto das mudanças de código nas métricas de negócio, facilitando a tomada de decisões baseadas em dados.

Implementar essa solução não apenas melhora a comunicação entre equipes técnicas e de marketing, mas também proporciona um registro histórico valioso de todas as alterações significativas no site.

Se você está buscando explorar ainda mais as capacidades do GA4, recomendamos ler nossos artigos sobre eventos no GA4, segmentos no GA4 e atualizações recentes do GA4.

Recursos Adicionais

• Documentação da API do Google Analytics Admin
• Documentação do GitHub Actions
• Autenticação com API do Google
• Nosso artigo sobre ferramentas de análise de dados

Próximos Passos

Para expandir essa integração, você pode considerar:

1. Adicionar mais informações nas anotações, como detalhes sobre o que mudou
2. Criar anotações apenas para tags de release, não para cada push
3. Incluir informações de testes A/B nas anotações
4. Integrar com outras ferramentas de monitoramento

Com essa integração implementada, equipes técnicas e de marketing podem trabalhar juntas de forma mais eficiente, usando dados para melhorar continuamente a experiência do usuário e o desempenho do site.