Problemas do GitHub
Corrija loops de instalação do GitHub App, organizações e repositórios ausentes, webhooks com falha, erros de permissão e branches incompatíveis.
A maioria dos problemas de integração com o GitHub está relacionada a permissões, falhas de webhook ou incompatibilidades de branch.
Organização não aparece durante a configuração
Durante o fluxo de configuração dos documentos iniciais, o Jamdesk mostra suas organizações do GitHub para que você escolha onde criar o repositório. A lista vem da API OAuth do GitHub, e o GitHub oculta organizações em dois casos:
- Restrições do app OAuth: sua organização restringe o acesso de apps de terceiros (padrão do GitHub para organizações novas) e ainda não aprovou o Jamdesk.
- SAML SSO: sua organização exige autenticação SAML antes que a API a retorne.
Se você é proprietário da organização, pode aprovar o Jamdesk imediatamente:
- Clique em grant Jamdesk access on GitHub abaixo do seletor de organizações (ou acesse GitHub → Settings → Applications → Authorized OAuth Apps → Jamdesk)
- Em Organization access, clique em Grant ao lado da sua organização
- De volta ao fluxo de configuração do Jamdesk, clique em refresh the list. Sua organização aparecerá imediatamente
Se você for membro (não proprietário), verá um botão Request; clicar nele enviará uma solicitação de aprovação aos administradores da organização.
Se você é membro sem direitos de proprietário, envie primeiro uma solicitação de aprovação aos administradores:
- Acesse GitHub → Settings → Applications → Authorized OAuth Apps → Jamdesk
- Em Organization access, clique em Request ao lado da sua organização. Isso notificará os administradores
- Um administrador aprova a solicitação em Settings → Third-party access → OAuth application policy da organização (as solicitações pendentes mostram um botão Approve)
- Retorne ao fluxo de configuração do Jamdesk e clique em refresh the list; sua organização deverá aparecer
Consulte o guia do GitHub sobre como aprovar apps OAuth para sua organização para ver as etapas detalhadas.
Não quer esperar a aprovação do administrador? Escolha sua conta pessoal durante a configuração e transfira o repositório para sua organização depois:
- Conclua a configuração do Jamdesk usando sua conta pessoal
- Acesse o repositório criado no GitHub
- Navegue até Settings → General → Danger Zone
- Clique em Transfer e selecione sua organização como destino
- No Jamdesk, desconecte e reconecte o repositório na página Settings do seu projeto
Desconectar e reconectar gera uma nova URL de documentos (por exemplo, your-project.jamdesk.app pode mudar). Se você já compartilhou sua URL ou configurou um domínio personalizado, entre em contato com o suporte antes de desconectar para preservarmos sua configuração.
Isso não funciona se sua empresa gerencia sua conta do GitHub. Consulte Contas do GitHub gerenciadas pela empresa.
Contas do GitHub gerenciadas pela empresa
Se sua empresa gerencia sua conta do GitHub (o GitHub as chama de Enterprise Managed Users, ou EMU), o GitHub não permite instalar apps na sua própria conta, apenas em uma organização. Se não houver uma organização disponível, clicar em Install no GitHub simplesmente levará você de volta à página do app Jamdesk. Durante o cadastro, o Jamdesk mostra "Your organization manages this GitHub account".
Nomes de usuário gerenciados terminam com um sublinhado e um código da empresa, como jsmith_acme. O GitHub explica as limitações em sua página sobre contas de usuário gerenciadas.
Você pode resolver isso de duas maneiras.
- Peça a um proprietário da empresa para criar uma organização na guia Organizations da sua empresa. Peça que ele permita que você crie repositórios nela.
- Transfira seu repositório de documentos para ela. No repositório, acesse Settings, clique em Transfer na parte inferior e escolha a nova organização.
- No Jamdesk, clique em Connect an existing repository (ou em Install GitHub App nas configurações do projeto). No GitHub, escolha a organização, selecione Only select repositories, selecione seu repositório e instale.
Se o GitHub mostrar Request em vez de Install, um proprietário da organização receberá um e-mail para aprovar. Clique novamente no botão do Jamdesk depois da aprovação.
Use esta opção se sua empresa não puder adicionar uma organização. Consulte primeiro o administrador do GitHub, pois os documentos ficarão fora do GitHub da empresa.
- Em uma janela privada do navegador, entre no GitHub com uma conta pessoal (ou crie uma).
- Crie um repositório privado vazio nessa conta.
- Envie uma cópia dos seus documentos para ele. O GitHub não pode transferir repositórios para fora de uma empresa gerenciada, portanto é necessária uma cópia.
git remote set-url origin https://jsmith@github.com/jsmith/product-docs.git
git push -u origin mainMantenha jsmith@ na URL para que o Git solicite as credenciais da sua conta pessoal.
- No Jamdesk, clique em Connect an existing repository (ou em Install GitHub App nas configurações do projeto), instale o Jamdesk na sua conta pessoal e escolha o repositório.
Contas gerenciadas não podem enviar alterações para repositórios fora da sua empresa, portanto todas as pessoas que editarem os documentos precisarão de uma conta pessoal do GitHub. Adicione-as ao repositório como colaboradoras.
Repositório não aparece
Se o seu repositório não aparecer na lista:
- Acesse GitHub → Settings → Applications → Jamdesk
- Verifique se o acesso ao repositório foi concedido
- Clique em Configure para adicionar mais repositórios
Para repositórios de organizações:
- Um administrador da organização precisa aprovar o Jamdesk
- Acesse as configurações da organização → Third-party access
- Aprove a solicitação de acesso do Jamdesk
Repositórios privados exigem autorização do GitHub. Se necessário, autorize o Jamdesk novamente.
Builds não são acionados
Se os pushes não acionarem builds:
- Acesse seu repositório no GitHub
- Navegue até Settings → Webhooks
- Encontre o webhook do Jamdesk
- Verifique se há erros em "Recent Deliveries"
Os builds são acionados somente na branch configurada. Verifique Settings no Jamdesk.
- Acesse Settings do projeto no Jamdesk
- Clique em Re-sync GitHub
Erros de webhook
404 Not Found
Não foi possível alcançar o endpoint do webhook.
Correção: sincronize novamente a conexão com o GitHub nas configurações do projeto.
401 Unauthorized
A autenticação falhou.
Correção:
- Acesse as configurações da sua conta do GitHub
- Navegue até Applications → Authorized OAuth Apps
- Revogue o Jamdesk
- Autorize novamente nas configurações do Jamdesk
500 Server Error
Problema temporário do Jamdesk.
Correção: aguarde alguns minutos e faça um novo push ou acione um rebuild manual.
Erros de permissão
"Repository not found" durante o build:
- O repositório pode ter sido excluído ou renomeado
- O Jamdesk pode ter perdido o acesso
- Autorize novamente sua conexão com o GitHub
Problemas de branch
Build na branch errada
Verifique a branch configurada em Settings → Repository.
Branch renomeada ou excluída
Atualize a configuração da branch para corresponder ao novo nome.
