Skip to main content
Se você deseja executar o Kody com um GitHub App, precisa criar um. Este app permite que o Kody interaja com seus repositórios, gerencie pull requests e receba webhooks.
Se quiser habilitar “Entrar com GitHub” para usuários da plataforma, esse é um processo separado de OAuth App e não interfere nas permissões do GitHub App. Este guia foca na integração funcional. Veja OAuth App do GitHub.

​
Pré-requisitos

Tenha os domínios da sua aplicação prontos:
  • WEB_DOMAIN: Sua URL de Frontend (ex.: https://app.yourdomain.com ou http://localhost:3000)
  • API_DOMAIN: Sua URL de Backend/API (ex.: https://api.yourdomain.com ou http://localhost:3000 para configurações monorepo/proxy)
  • WEBHOOK_DOMAIN (opcional): Domínio público para webhooks (ex.: https://kodus-webhooks.yourdomain.com). Se você roteia /.../webhook no domínio da API, pode usar API_DOMAIN.

​
Passo 1: Criar o GitHub App

  1. No GitHub, vá em Settings > Developer Settings > GitHub Apps
  2. Clique em New GitHub App
  3. Preencha as informações básicas (Nome, Homepage URL) de acordo com sua preferência
Página de configurações do GitHub Apps destacando o botão New GitHub App

​
Passo 2: Configurar URLs de Callback e Setup

Webhook do GitHub App Esta etapa é fundamental para garantir que a instalação e o redirecionamento funcionem corretamente. Preencha os campos abaixo, substituindo WEB_DOMAIN pela sua URL real:
  • Callback URL:
    Esta URL é usada para concluir o fluxo de autorização.
  • Setup URL:
  • Marque a opção: Redirect on update Isso garante que, após instalar o app, os usuários sejam redirecionados de volta ao Kodus para concluir a configuração.

​
Passo 3: Configurar o Webhook

O webhook notifica o Kodus sobre eventos nos seus pull requests.
Os webhooks são tratados por um serviço separado (porta 3332). Se usar o domínio da API aqui, certifique-se de que seu proxy reverso roteia /github/webhook para o serviço de webhooks. Caso contrário, use um domínio dedicado para webhooks.
  • Webhook URL:
  • Certifique-se de que a opção Active está marcada

​
Configurar permissões do repositório e eventos

Em Repository permissions, configure os acessos abaixo conforme as funcionalidades habilitadas. Não deixe todas as permissões em No access. Escrita em Contents só é necessária para funcionalidades que criam commits; somente leitura basta para ler código. Instale o app nos repositórios desejados e aprove novas permissões nas instalações existentes. Assine Pull request, Pull request review comment, Issue comment e Push. O handler atual aceita esses quatro eventos; outros podem retornar 200 mesmo sendo ignorados.

​
Passo 4: Coletar Credenciais e Adicionar ao .env

Webhook do GitHub App Agora você precisa obter as credenciais geradas pelo GitHub e adicioná-las às suas variáveis de ambiente do Kodus.

​
App ID

No topo da página “About” do seu app, copie o App ID. Adicione ao seu .env:

​
Client Secret

Vá para a seção Client secrets e clique em Generate a new client secret. Copie o valor gerado. Adicione ao seu .env:

​
Private Key

Role até o final da página e clique em Generate a private key. Isso fará o download de um arquivo .pem. Abra este arquivo com um editor de texto e copie todo o conteúdo. Adicione ao seu .env:

​
Installation URL

Abra seu GitHub App e clique em Install App. Copie a URL da barra de endereços do navegador (ela se parece com https://github.com/apps/<app-slug>/installations/new). Adicione ao seu .env:

​
Resumo das Variáveis de Ambiente

Ao final, seu arquivo de configuração deve conter:
Clique em Save Changes no GitHub e reinicie sua aplicação Kodus para aplicar as alterações.

​
Verificar a conexão

A URL do webhook deve alcançar o serviço de webhooks, não o login do frontend. Use API_DOMAIN apenas se o proxy encaminhar /github/webhook para esse serviço; nem WEB_DOMAIN nem uma resposta 200/307 comprovam a entrega correta. Mantenha Redirect on update ativado. Após instalar ou alterar o acesso aos repositórios, conclua o retorno do navegador ao Kodus pela Setup URL. Um ping bem-sucedido ou um evento installation ignorado não cria a integração no Kodus. Em Git Settings do Kodus, confirme que o repositório esperado está conectado. Abra um pull request de teste e confira a resposta de entrega do GitHub e os logs de webhooks/worker do Kodus. Se a conexão não aparecer, confira acesso aos repositórios, permissões aprovadas, Setup URL e proxy. Referência de registro no GitHub.