GitHub

A integração com o GitHub permite conectar seus repositórios de código ao Almirant para vincular pull requests e commits a work items, visualizar a atividade de desenvolvimento diretamente no quadro e fornecer contexto aos agentes de IA sobre o código do projeto.

Pré-requisitos

A integração com o GitHub é controlada por uma feature flag. Para que ela esteja disponível na sua instância do Almirant, a variável de ambiente NEXT_PUBLIC_FEATURE_GITHUB deve estar ativada.

Conectar o GitHub

A conexão é feita por meio de uma instalação de OAuth App do GitHub no nível da organização:

1. Acesse Configurações > Integrações > GitHub.
2. Clique em Conectar GitHub.
3. O GitHub solicitará que você autorize o Almirant como OAuth App.
4. Selecione a organização ou conta na qual deseja instalar a aplicação.
5. Escolha os repositórios aos quais o Almirant terá acesso (todos ou selecionados).
6. Confirme a instalação.

Após a conclusão, você verá o status da conexão e os repositórios disponíveis nas configurações de integrações.

Repositórios selecionados

Recomendamos conceder acesso apenas aos repositórios que você vinculará a projetos no Almirant, em vez de conceder acesso a todos. Você pode alterar as permissões posteriormente nas configurações do GitHub.

Vincular repositórios a um projeto

Depois de conectar o GitHub, você pode vincular um ou mais repositórios a cada projeto:

1. Acesse o projeto ao qual deseja vincular repositórios.
2. Vá para a seção Repositórios.
3. Clique em Vincular repositório.
4. Selecione o repositório na lista de repositórios disponíveis.
5. Confirme o vínculo.

O repositório fica associado ao projeto e toda a sua atividade passa a ficar visível no Almirant.

Pull requests e work items

Uma das funcionalidades mais úteis da integração é o vínculo automático entre pull requests e work items.

Como vincular um PR a um work item

Inclua o identificador do work item (por exemplo, A-T-42) no título ou na descrição do pull request no GitHub. O Almirant detectará a referência e vinculará o PR automaticamente.

Exemplo de título de PR:

feat: Implementar sistema de notificações [A-T-42]

Exemplo na descrição do PR:

## Descripcion
Implementa el sistema de notificaciones push.

Relacionado con: A-T-42

Ver PRs no Almirant

Nos detalhes de um work item, você pode ver todos os pull requests vinculados, incluindo:

• Status do PR (aberto, fechado, merged).
• Autor e data de criação.
• Link direto para o PR no GitHub.

Ver commits associados

Além dos pull requests, o Almirant mostra os commits associados ao work item, oferecendo rastreabilidade completa do código vinculado a cada tarefa.

Atividade de desenvolvimento

Na visualização do projeto, a seção de repositórios mostra um resumo da atividade recente de desenvolvimento:

• Últimos commits nas branches principais.
• Pull requests abertos e seus status.
• Atividade dos membros da equipe nos repositórios.

Contexto para agentes de IA

Quando um repositório está vinculado a um projeto, os agentes de IA podem acessar o contexto do código para:

• Entender a estrutura do projeto ao implementar novas features.
• Revisar código existente durante um code review.
• Gerar testes com base na implementação atual.
• Responder a perguntas técnicas com conhecimento da base de código real.

Desconectar o GitHub

Para desconectar a integração com o GitHub:

1. Acesse Configurações > Integrações > GitHub.
2. Clique em Desconectar.
3. Confirme a desconexão.

aviso

Desconectar o GitHub removerá o vínculo dos repositórios com os projetos. Os work items manterão as referências históricas a PRs e commits, mas não serão atualizados com novas informações.

Para desenvolvedores

Variáveis de ambiente

Variável	Descrição	Obrigatória
NEXT_PUBLIC_FEATURE_GITHUB	Feature flag que ativa a integração com o GitHub no frontend	Sim
GITHUB_CLIENT_ID	Client ID da OAuth App do GitHub	Sim
GITHUB_CLIENT_SECRET	Client Secret da OAuth App do GitHub	Sim

Arquitetura da integração

A integração é composta por:

• Frontend: Domínio github em frontend/src/domains/github/, com hooks para a instalação OAuth e o vínculo de repositórios.
• Backend: Rotas em backend/api/src/routes/ para gerenciar instalações e repositórios.
• Banco de dados: Tabelas githubInstallations e repositories no schema.
• Webhooks: Endpoint que recebe eventos do GitHub (push, PR) e atualiza as informações no Almirant.