Conectar GitHub
Conecte seu repositório do GitHub ao Jamdesk para implantações automáticas a cada push. Cobre instalação do app, seleção de repositório e configuração de branch.
O Jamdesk implanta sua documentação automaticamente quando você faz push para o GitHub.
As capturas de tela mostram a interface em inglês.
Para entender como o GitHub App e a vinculação de conta pessoal funcionam juntos, consulte Entendendo a integração com o GitHub.
Documentação no Bitbucket Cloud? Consulte Conectar Bitbucket. Cada projeto se conecta a um provedor. Sem conta no GitHub? Consulte Documentação sem GitHub.
Instalação do GitHub App
O Jamdesk solicita que você instale o GitHub App do Jamdesk na primeira vez que fizer login. O app concede:
- Acesso ao repositório: ler o conteúdo da sua documentação
- Webhooks: acionar builds a cada push
- Status de 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 e escrita) | Clonar e ler seus arquivos de documentação. As gravações acontecem somente quando você salva no editor do dashboard, aceita sugestões do Fix with AI ou ativa a tradução |
| Metadados (leitura) | Listar repositórios e branches |
| Webhooks | Receber notificações de push |
O Jamdesk acessa apenas os repositórios para os quais você concedeu acesso explicitamente. Altere o acesso a qualquer momento nas configurações do seu GitHub.
Conectar um repositório
Clique em Connect Repository ao criar ou editar um projeto.
Escolha entre os repositórios em que o GitHub App está instalado.
Selecione a branch a ser implantada:
- main ou master: mais comum para documentação de produção
- docs: se você mantém a documentação em uma branch separada
- Qualquer branch: para implantações de preview
Se o seu 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 o docs.json estiver na raiz.
O painel do projeto então mostra o repositório e a branch vinculados:
Deploys automáticos
Cada push para a branch configurada aciona um build:
git add .
git commit -m "Update API documentation"
git push origin main
Os builds normalmente terminam em 30 a 90 segundos. Veja o status no painel 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
Trocar de repositório pode afetar sua documentação ao vivo. 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 de organizações
Um administrador da organização deve aprovar a instalação do GitHub App para repositórios de organizações:
- Solicite a instalação no seu dashboard do Jamdesk
- Um administrador recebe uma notificação no GitHub
- Os repositórios da organização aparecem no seletor de repositórios após a aprovação
Vincular sua conta pessoal
Vincule sua conta pessoal do GitHub em User Settings para uma atribuição confiável dos builds:
- Clique no seu avatar → User Settings
- Encontre a seção GitHub Account
- Clique em Link GitHub Account
Esse vínculo é separado do GitHub App. Ele atribui seus commits 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 que um administrador aprovou o acesso
- Atualize a lista de repositórios no dashboard
O GitHub continua redirecionando você para a página do app do Jamdesk
Sua empresa provavelmente gerencia sua conta do GitHub. O GitHub não permite que essas contas instalem apps por conta própria. Consulte contas do GitHub gerenciadas pela empresa para resolver.
Usar uma conta do GitHub que outra conta do Jamdesk já utiliza
A lista de repositórios mostra uma mensagem que começa com:
Another Jamdesk account already uses this GitHub account.
Isso significa que um projeto de outra conta do Jamdesk já usa o GitHub App do Jamdesk nessa conta do GitHub. Normalmente, um colega configurou o Jamdesk primeiro, ou você está conectado a uma segunda conta do Jamdesk.
Para usar os repositórios dessa conta:
- Clique em Verify on GitHub.
- Faça login no GitHub com um usuário que possa fazer push no repositório.
- Escolha o repositório na lista.
Verify on GitHub vincula o usuário do GitHub com o qual você fez login à sua conta do Jamdesk, da mesma forma que User Settings faz. Se o seu navegador já estiver conectado ao GitHub com outra pessoa, saia do GitHub primeiro.
A lista mostra apenas os repositórios para os quais o seu usuário do GitHub pode fazer push. A verificação dura uma hora, então escolha o repositório logo após verificar. Se o Jamdesk informar que o GitHub não mostrou nenhuma instalação que você possa usar, confira se fez login com o usuário correto do GitHub. Ou peça a um proprietário da conta do GitHub que conceda acesso ao repositório.
Para trabalhar no mesmo projeto, peça ao proprietário dele que convide você.
Os builds não são acionados
- Verifique se o webhook está ativo nas configurações do repositório
- Confirme que você está fazendo push para a branch configurada
- Procure erros de entrega de webhook no GitHub
Erros de permissão negada
- Autorize novamente o GitHub App nas suas configurações do GitHub
- Confirme que o GitHub App do Jamdesk pode acessar o repositório
Para uma solução de problemas mais detalhada, consulte Entendendo a integração com o GitHub.
