Conectar GitHub
Conecte seu repositório GitHub ao Jamdesk para implantações automáticas a cada push, configurando o app, o repositório e a branch.
O Jamdesk integra-se ao GitHub para implantar automaticamente 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.
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 a cada 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 apenas os repositórios aos quais você concede explicitamente acesso. 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 a ser implantada:
- main ou master - Mais comum para documentação em produção
- docs - Se você mantiver a documentação em uma branch separada
- Qualquer branch - Para implantações de pré-visualização
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:
Implantações automáticas
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 a 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 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 a 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 da organização
Para repositórios de uma organização, um administrador da organização deve aprovar a instalação do GitHub App:
- Solicite a instalação no dashboard do Jamdesk
- Um administrador receberá uma notificação no GitHub
- Depois da aprovação, os repositórios da organização aparecerão 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
Builds não são acionados
- Verifique se o webhook está ativo nas configurações do repositório
- Confirme se você está enviando alterações 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
- Confirme 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.