> ## Documentation Index
> Fetch the complete documentation index at: https://docs.synkrony.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Integração com GitHub

> Conecte seus repositórios e automatize o fluxo de trabalho

# 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ção            | Status Resultado                         |
| ------------------- | ---------------------------------------- |
| PR normal           | Move para o status mapeado como `review` |
| PR em draft         | Permanece no status atual                |
| Tarefa já concluída | Nã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ção                | Status Resultado                           |
| ----------------------- | ------------------------------------------ |
| Revisão aprovada        | Move para o status mapeado como `approved` |
| Revisor é o autor do PR | Não sofre alteração                        |
| Tarefa já concluída     | Nã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ção                  | Status Resultado              |
| ------------------------- | ----------------------------- |
| Alterações solicitadas    | Move para `changes_requested` |
| Comentário de revisor     | Move para `changes_requested` |
| Comentário de não-revisor | Não sofre alteração           |

### ✅ PR Mergeado (Merged)

O evento final do ciclo de vida do PR:

| Condição             | Status Resultado                      |
| -------------------- | ------------------------------------- |
| PR mergeado          | Move para `done`                      |
| Task Execution ativa | Marca a execução como concluída       |
| Feedback ativo       | Adiciona comentário de feedback no PR |

### 📝 PR Editado

Atualizações nas informações do PR:

| Alteração         | Comportamento                                             |
| ----------------- | --------------------------------------------------------- |
| Draft → Não-draft | Se o status não tem mapeamento GitHub, move para `review` |
| Não-draft → Draft | Define flag de draft                                      |
| Outras edições    | Apenas atualiza metadados                                 |

### 🔁 PR Reaberto (Reopened)

| Condição    | Status Resultado           |
| ----------- | -------------------------- |
| PR reaberto | Move para `review`         |
| Metadados   | Atualiza informações do PR |

### ❌ PR Fechado (Closed)

| Condição                  | Status 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:

| Evento                        | Descrição                                                     |
| ----------------------------- | ------------------------------------------------------------- |
| `pull_request`                | Abertura, edição, fechamento, merge ou reabertura de PR       |
| `pull_request_review`         | Submissão de review (approved, changes\_requested, commented) |
| `pull_request_review_comment` | Comentários em linhas específicas de código                   |
| `issue_comment`               | Comentários gerais no PR                                      |
| `check_run`                   | Status de GitHub Actions                                      |
| `installation`                | Instalação/desinstalação do GitHub App                        |
| `installation_repositories`   | Alteraçã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 Synkrony      | GitHub Status Type  |
| ----------------------- | ------------------- |
| Aguardando Revisão      | `review`            |
| Alterações Requisitadas | `changes_requested` |
| Aprovado (se existir)   | `approved`          |
| Done                    | `done`              |

***

## 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?