Skip to main content

​
Integração com GitHub

A integração do Synkrony com GitHub permite automatizar atualizações de status das tarefas com base em eventos de Pull Request, eliminando trabalho manual e garantindo que o kanban reflita sempre a situação real do desenvolvimento.

​
Como Funciona

O Synkrony utiliza GitHub App e webhooks para monitorar eventos em seus repositórios. Quando algo relevante acontece em um Pull Request, o sistema identifica automaticamente a tarefa relacionada e atualiza seu status.

​
Autenticação via GitHub App

Diferente de OAuth pessoal, o Synkrony usa GitHub App, que oferece:
  • ✅ Segurança aprimorada: Credenciais compartilhadas, não tokens pessoais
  • ✅ Escopo configurável: Acesso apenas aos repositórios necessários
  • ✅ Automação-friendly: Ideal para integrações CI/CD
  • ✅ Gerenciamento centralizado: Administradores controlam o acesso

​
Vinculando Tarefas a Pull Requests

​
Método 1: Slug no Título (Recomendado)

Inclua o slug da tarefa no título do PR:
  • Exemplo simples: [SW-123] Implementar autenticação
  • Múltiplas tarefas: [SW-123] [SW-456] Atualizar API

​
Método 2: URL do PR

Se nenhum slug for encontrado, o sistema usa a URL do PR como referência.

​
Fluxo de Automação

A seguir, o comportamento de cada evento de Pull Request:

​
📌 PR Aberto (Opened)

CondiçãoStatus Resultado
PR normalMove para o status mapeado como review
PR em draftPermanece no status atual
Tarefa já concluídaNão sofre alteração
Dados armazenados na tarefa:
  • URL do Pull Request
  • Repositório GitHub
  • Autor do PR
  • Número do PR
  • Data de criação
  • Flag indicando se é draft

​
👍 PR Aprovado (Approved)

Disparado quando um revisor aprova o PR:
CondiçãoStatus Resultado
Revisão aprovadaMove para o status mapeado como approved
Revisor é o autor do PRNão sofre alteração
Tarefa já concluídaNão sofre alteração

​
🔄 Alterações Solicitadas (Changes Requested)

Disparado por dois eventos:
  1. Review formal: Revisor marca como “changes requested”
  2. Comentário de revisor: Qualquer comentário de um revisor solicitado no PR
CondiçãoStatus Resultado
Alterações solicitadasMove para changes_requested
Comentário de revisorMove para changes_requested
Comentário de não-revisorNão sofre alteração

​
✅ PR Mergeado (Merged)

O evento final do ciclo de vida do PR:
CondiçãoStatus Resultado
PR mergeadoMove para done
Task Execution ativaMarca a execução como concluída
Feedback ativoAdiciona comentário de feedback no PR

​
📝 PR Editado

Atualizações nas informações do PR:
AlteraçãoComportamento
Draft → Não-draftSe o status não tem mapeamento GitHub, move para review
Não-draft → DraftDefine flag de draft
Outras ediçõesApenas atualiza metadados

​
🔁 PR Reaberto (Reopened)

CondiçãoStatus Resultado
PR reabertoMove para review
MetadadosAtualiza informações do PR

​
❌ PR Fechado (Closed)

CondiçãoStatus Resultado
PR fechado (não mergeado)Não sofre alteração de status
Importante: Apenas PRs mergeados movem tarefas para “Done”. PRs fechados sem merge não alteram o status.

​
Eventos de Webhook Suportados

O Synkrony processa os seguintes eventos do GitHub:
EventoDescrição
pull_requestAbertura, edição, fechamento, merge ou reabertura de PR
pull_request_reviewSubmissão de review (approved, changes_requested, commented)
pull_request_review_commentComentários em linhas específicas de código
issue_commentComentários gerais no PR
check_runStatus de GitHub Actions
installationInstalação/desinstalação do GitHub App
installation_repositoriesAlteração de repositórios configurados

​
Segurança

​
Validação de Webhooks

  • Assinatura HMAC: Cada webhook é validado usando X-Hub-Signature-256
  • Segredo compartilhado: Garante que apenas eventos legítimos do GitHub são processados
  • Filtro de bots: Ignora eventos de GitHub bots para evitar loops infinitos

​
Instalação por Empresa

Cada empresa pode instalar o GitHub App do Synkrony com opções:
  • Todos os repositórios: Acesso completo à conta da organização
  • Repositórios selecionados: Apenas aos repositórios escolhidos

​
Configuração Passo a Passo

​
1. Acesse as Configurações

Navegue para Configurações → GitHub

​
2. Instale o GitHub App

Clique em Instalar GitHub App e escolha:
  • Conta pessoal ou organização do GitHub
  • Repositórios desejados (todos ou selecionados)

​
3. Configure o Mapeamento de Status

Certifique-se de que os status do Synkrony estão mapeados corretamente:
Status do SynkronyGitHub Status Type
Aguardando Revisãoreview
Alterações Requisitadaschanges_requested
Aprovado (se existir)approved
Donedone

​
Exemplo Prático de Fluxo

1. Desenvolvedor cria tarefa "SW-123" no Synkrony
   → Status: "A Fazer"

2. Dev começa a trabalhar na tarefa
   → Move manualmente para "Em Andamento"

3. Dev cria PR draft: "[SW-123] Implementar feature"
   → Status permanece "Em Andamento" (é draft)

4. Dev marca PR como pronto para review
   → Status move automaticamente para "Aguardando Revisão"

5. Revisor aprova o PR
   → Status move automaticamente para "Aprovado"

6. Revisor solicita alterações via review
   → Status move automaticamente para "Alterações Requisitadas"

7. Dev faz ajustes e solicita novo review
   → Status move automaticamente para "Aguardando Revisão"

8. PR é mergeado
   → Status move automaticamente para "Done"
   → Comentário de feedback é adicionado no PR

​
Comportamentos Especiais

​
Draft PRs

Pull Requests em draft não movem tarefas para review. Eles permanecem no status atual (geralmente “Em Andamento”) até que sejam marcados como prontos para review.
A PR é considerada draft se o título contém “[draft]” ou “draft”

​
Múltiplas Tarefas em um PR

Um único PR pode referenciar múltiplas tarefas incluindo vários slugs no título: 
[SW-123] [SW-456] Feature completa com backend e frontend
Todas as tarefas mencionadas serão atualizadas simultaneamente.

​
❓ FAQ

Posso ter múltiplos status com o mesmo github_status_type? Não. Por empresa, apenas um status pode ter cada tipo de mapeamento GitHub. Isso garante clareza na automação. O que acontece se eu não configurar os mapeamentos GitHub? O Synkrony já vem com status pré-configurados. Você pode personalizá-los, mas não é obrigatório para o funcionamento básico. PRs de draft afetam o status da tarefa? Não. PRs em draft não movem a tarefa para “Review”, ela permanece no status atual. O que acontece se eu fechar um PR sem merge? A tarefa NÃO move para “Done”. Ela permanece no status atual, permitindo que você decida o próximo passo manualmente. Como desconectar um PR de uma tarefa? Atualmente não é possível desconectar. Edite o título do PR removendo o slug ou crie um novo PR. A integração funciona com repositórios privados? Sim! O GitHub App funciona com repositórios públicos e privados, desde que devidamente configurado. Posso usar a integração sem ter os status configurados? Sim, mas a automação não funcionará corretamente. Certifique-se de configurar pelo menos os status de review, changes_requested e done.

​
Troubleshooting

​
O PR não está movendo a tarefa

Verifique:
  1. O slug da tarefa está no título do PR?
  2. O status de destino está configurado com o github_status_type correto?
  3. O repositório está configurado no GitHub App?

​
A tarefa moveu para o status errado

Verifique:
  1. Os mapeamentos de github_status_type estão corretos?
  2. Há múltiplos status com o mesmo mapeamento?

​
Eventos não estão sendo processados

Verifique:
  1. O GitHub App está instalado na organização correta?
  2. O repositório tem permissão para enviar webhooks?