Conectar o GitHub
Conectar o GitHub leva menos de um minuto e é feito por um GitHub App com permissões somente leitura. Você instala o app na sua conta ou organização, escolhe exatamente quais repositórios ele pode ler, e nenhum código é alterado. A partir daí, a plataforma passa a ler PRs, reviews, commits, deployments, CI e mais para calcular as métricas de engenharia.
Visão geral#
O GitHub é o provedor de código mais usado na plataforma. A conexão é somente leitura: a Mensor lê a atividade dos repositórios que a instalação conceder e transforma esses metadados em métricas, dashboards e insights. Em nenhum momento ela escreve nos seus repositórios, abre PRs, comenta ou altera código.
O fluxo tem quatro etapas:
- Autorizar no GitHub (identifica quem está conectando).
- Instalar o app na conta ou organização, escolhendo os repositórios (só na primeira vez).
- Selecionar na plataforma quais desses repositórios deseja acompanhar.
- Ativar para iniciar a sincronização.
Privacidade: o acesso é somente leitura e definido pela instalação. O sync usa tokens de instalação de curta duração (renovados automaticamente), as credenciais são criptografadas (AES-256) no banco e a plataforma não armazena o conteúdo do código-fonte, apenas metadados (PRs, reviews, commits, timestamps, etc.).
Pré-requisitos#
- Ser Owner ou Admin da organização na plataforma Mensor para criar/conectar integrações.
- Ter uma conta GitHub com acesso aos repositórios que deseja acompanhar.
- Para instalar o app numa organização do GitHub, é preciso ser owner dela. Se você não for, a instalação vira uma solicitação que um owner aprova; depois da aprovação, é só voltar e concluir a conexão.
Passo a passo#
- No menu lateral do app, abra Integrações.
- No card do GitHub, clique em Conectar.
- Você será redirecionado ao GitHub para autorizar. Na primeira conexão, o GitHub também pede para instalar o app: escolha a conta ou organização e quais repositórios ele pode ler (todos ou uma seleção).
- De volta à plataforma, selecione os repositórios que deseja acompanhar (entre os que a instalação concedeu).
- Clique em Ativar: a sincronização começa imediatamente em segundo plano.
Se você autorizou mas ainda não instalou o app em nenhuma conta, a plataforma mostra o passo "Instale o GitHub App" com o link de instalação. Instale na aba que abrir, volte e clique em "Já instalei, atualizar".
Permissões do app (somente leitura)#
O acesso é definido pelas permissões declaradas no app, todas de leitura, e vale só para os repositórios que a instalação conceder:
| Permissão | Para quê |
|---|---|
| Metadata | Informações básicas dos repositórios (obrigatória) |
| Contents | Commits, branches e arquivos (ex.: CODEOWNERS) |
| Pull requests | PRs, reviews e comentários |
| Issues | Issues e milestones |
| Actions | Workflow runs (CI) |
| Deployments | Deployments (base do DORA) |
| Projects | Projects v2 (sprints/iterations) |
| Dependabot alerts | Alertas de dependências vulneráveis |
| Code scanning alerts | Alertas de análise de código |
| Copilot Business (da org) | Uso agregado do Copilot (tela de Uso de IA) |
As credenciais são criptografadas (AES-256) no banco. O sync usa tokens de instalação que expiram em cerca de uma hora e são renovados automaticamente.
Por que um GitHub App?#
Diferente do OAuth clássico (cujo escopo repo concede leitura e escrita em tudo), o GitHub App tem
permissões granulares e somente leitura, limitadas aos repositórios da instalação. Você enxerga
exatamente o que foi concedido, ajusta a seleção de repositórios a qualquer momento nas configurações da
instalação, e pode desinstalar o app no GitHub para revogar todo o acesso na hora.
Webhooks (atualização em tempo real)#
Após o full sync, os dados seguem atualizados por webhooks automáticos: eles fazem parte do app, então começam a chegar assim que a instalação é feita, sem nenhuma configuração manual. Cada evento é protegido por assinatura HMAC-SHA256: eventos sem assinatura válida são rejeitados. Como rede de segurança, uma reconciliação automática re-varre os repositórios ativos periodicamente, então nenhum evento perdido vira buraco permanente.
O que é sincronizado#
Para cada repositório que você ativar, a plataforma importa:
- Pull requests (com os timestamps de ciclo: abertura, primeiro review, merge).
- Reviews e comentários (de linha e gerais).
- Commits e arquivos alterados.
- Deployments (base para o DORA).
- Workflow runs (GitHub Actions / CI): sucesso/falha e duração.
- Issues e milestones.
- Projects v2 (sprints/iterations).
- Alertas de segurança (Dependabot e code scanning).
- CODEOWNERS.
Os detalhes do processo de importação estão em Selecionar repositórios e sincronizar.
Status da conexão#
Na tela de Integrações, o card do GitHub mostra o status atual da conexão:
| Status | O que significa | O que fazer |
|---|---|---|
| ACTIVE | Conectado e funcionando; exibe a contagem de repositórios ativos | Nada, está tudo certo |
| EXPIRED | A autorização precisa ser renovada (ex.: app desinstalado no GitHub, ou a migração da plataforma para o GitHub App) | Clique em Reconectar e refaça a autorização |
| ERROR | Houve uma falha de autenticação ou de acesso | Tente reconectar; veja a seção de problemas |
Reconectar / trocar de conta#
Quando o status fica EXPIRED ou ERROR, basta clicar em Reconectar no card do GitHub e refazer a autorização. Os repositórios já ativos permanecem selecionados; você pode ajustar a seleção depois. Para trocar de organização, use o seletor de conta na tela de repositórios: cada opção é uma instalação do app. Se a organização desejada não aparece, instale o app nela no GitHub.
Reconectar não apaga os dados já sincronizados: ele apenas renova o acesso para que a sincronização incremental continue funcionando.
Solução de problemas (FAQ)#
Não vejo meus repositórios privados#
A lista vem dos repositórios que a instalação concede. Abra as configurações da instalação no GitHub (Settings, Integrations, o app da Mensor) e ajuste a seleção de repositórios; depois volte e atualize.
Não consigo ver os repositórios da minha organização#
Instalar o app numa organização exige owner da organização no GitHub. Se você não for, a instalação vira uma solicitação pendente; peça a um owner para aprová-la e depois conclua a conexão.
Por que a conexão é somente leitura?#
Para calcular métricas, a plataforma só precisa ler a atividade. O GitHub App declara permissões somente leitura, então nem tecnicamente é possível abrir PRs, comentar, fazer merge ou alterar configurações. O conteúdo do código-fonte não é armazenado, apenas metadados.
O status mudou para EXPIRED: perdi meus dados?#
Não. EXPIRED significa apenas que a autorização precisa ser renovada (por exemplo, o app foi desinstalado ou suspenso no GitHub). Os dados já sincronizados continuam disponíveis. Reconecte para retomar a sincronização incremental.
Minha conexão apareceu como Expirado depois de uma atualização da plataforma#
Esperado: a conexão do GitHub migrou do OAuth clássico para o GitHub App. Clique em Reconectar, autorize e instale o app; os repositórios ativos e todo o histórico ficam intactos.
Conectei, mas as métricas estão vazias#
Verifique se você ativou ao menos um repositório e acompanhe o status do full sync em Selecionar repositórios e sincronizar. As métricas aparecem conforme a primeira carga é concluída.
Próximos passos#
- Selecionar repositórios e acompanhar a sincronização.
- Abrir o Overview e dashboards para ver as métricas.
- Conectar também o Jira (planejamento) ou o Azure DevOps.