Conectar GitHub
Conecte seu repositório do GitHub ao Jamdesk para deploys automáticos a cada push, com instalação do app, seleção do repositório e configuração da branch.
O Jamdesk integra-se ao GitHub para fazer o deploy automático da sua documentação quando você envia alterações.
As capturas de tela mostram a interface em inglês.
Para entender como o GitHub App e a vinculação da conta pessoal funcionam em conjunto, consulte Entender a integração com o GitHub.
A documentação está no Bitbucket Cloud? Consulte Conectar Bitbucket. Cada projeto se conecta a um único provedor.
Instalação do GitHub App
Ao entrar no Jamdesk pela primeira vez, você será solicitado a instalar o GitHub App do Jamdesk. Esse app permite:
- Acesso ao repositório - Ler o conteúdo da sua documentação
- Webhooks - Acionar builds ao fazer push
- Status do commit - Mostrar o status do build nos commits
Permissões
O GitHub App do Jamdesk solicita estas permissões:
| Permissão | Finalidade |
|---|---|
| Conteúdo do repositório (leitura) | Clonar e ler os arquivos da sua documentação |
| Metadados (leitura) | Listar repositórios e branches |
| Webhooks | Receber notificações de push |
O Jamdesk acessa somente os repositórios aos quais você concedeu acesso explicitamente. Você pode modificar o acesso a qualquer momento nas configurações do GitHub.
Conectar um repositório
Ao criar ou editar um projeto, clique em Connect Repository.
Escolha entre os repositórios nos quais o GitHub App está instalado.
Selecione a branch para fazer o deploy:
- main ou master - Mais comum para documentação em produção
- docs - Se você mantém a documentação em uma branch separada
- Qualquer branch - Para deploys de preview
Se o arquivo docs.json não estiver na raiz do repositório, especifique o caminho:
docs/ # Docs in a subdirectory
packages/docs/ # Monorepo with docs packageDeixe em branco se docs.json estiver na raiz.
Depois de conectado, o dashboard do projeto mostra o repositório e a branch vinculados:
Deploys automáticos
Depois de conectado, cada push para a branch configurada aciona um build:
git add .
git commit -m "Update API documentation"
git push origin mainOs builds normalmente são concluídos em 30–90 segundos. Veja o status no dashboard ou no commit do GitHub.
Alterar repositórios
Para conectar um repositório diferente:
- Acesse Settings → Repository
- Clique em Change Repository
- Selecione o novo repositório e a branch
Alterar os repositórios pode afetar sua documentação publicada. O novo repositório deve conter uma configuração válida do Jamdesk.
Gerenciar o acesso do GitHub App
Controle quais repositórios o Jamdesk pode acessar:
- Acesse github.com/settings/installations
- Encontre Jamdesk na lista
- Clique em Configure
- Em "Repository access", selecione repositórios específicos ou todos
Repositórios de organizações
Para repositórios de organizações, um administrador da organização precisa aprovar a instalação do GitHub App:
- Solicite a instalação no dashboard do Jamdesk
- Um administrador recebe uma notificação no GitHub
- Depois da aprovação, os repositórios da organização aparecem no seletor de repositórios
Vincular sua conta pessoal
Para atribuir os builds de forma confiável, vincule sua conta pessoal do GitHub em User Settings:
- Clique no seu avatar → User Settings
- Encontre a seção GitHub Account
- Clique em Link GitHub Account
Isso é separado do GitHub App e garante que seus commits sejam atribuídos corretamente a você. Saiba mais.
Solução de problemas
Repositório não aparece
- Verifique se o GitHub App está instalado no repositório
- Para repositórios de organizações, confirme se um administrador aprovou o acesso
- Tente atualizar a lista de repositórios no dashboard
O GitHub continua redirecionando você para a página do app do Jamdesk
Provavelmente sua empresa gerencia sua conta do GitHub, e o GitHub não permite que essas contas instalem apps na própria conta. Consulte contas do GitHub gerenciadas pela empresa para corrigir o problema.
Os builds não são acionados
- Verifique se o webhook está ativo nas configurações do repositório
- Confirme se você está fazendo push para a branch configurada
- Procure erros de entrega do webhook no GitHub
Erros de permissão negada
- Autorize novamente o GitHub App nas configurações do GitHub
- Verifique se o repositório está acessível ao Jamdesk App
Para obter informações mais detalhadas sobre a solução de problemas, consulte Entender a integração com o GitHub.