Problemas no GitHub
Resolva loops de instalação do app GitHub em contas gerenciadas pela empresa, organizações e repositórios ausentes, webhooks com falha e erros de permissão.
A maioria dos problemas de integração com o GitHub se deve a permissões, falhas de webhook ou incompatibilidades de branch.
Organização não aparece durante a configuração
O fluxo de configuração inicial lista suas organizações do GitHub. Escolha uma para hospedar o novo repositório. A lista vem da API OAuth do GitHub. O GitHub oculta uma organização dessa lista em dois casos:
- Restrições de app OAuth: sua organização restringe o acesso de apps de terceiros (padrão do GitHub para novas organizações) e ainda não aprovou o Jamdesk.
- SAML SSO: sua organização exige autenticação SAML antes que a API a retorne.
Aprove 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 aparece imediatamente
Membros (que não são proprietários) veem um botão Request. Ele envia uma solicitação de aprovação aos administradores da organização.
Envie uma solicitação de aprovação aos seus administradores:
- Acesse GitHub → Settings → Applications → Authorized OAuth Apps → Jamdesk
- Em Organization access, clique em Request ao lado da sua organização. Isso notifica os administradores da organização
- Um administrador aprova em Settings → Third-party access → OAuth application policy da organização (solicitações pendentes exibem um botão Approve)
- Volte ao fluxo de configuração do Jamdesk e clique em refresh the list. Sua organização deve aparecer agora
Consulte o guia do GitHub sobre aprovação de apps OAuth para sua organização para ver os passos detalhados.
Escolha sua conta pessoal durante a configuração para pular a aprovação do administrador. 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
- Abra 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 documentação (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. Podemos preservar sua configuração.
Isso não funciona se sua empresa gerencia sua conta do GitHub. Consulte contas do GitHub gerenciadas pela empresa.
Contas GitHub gerenciadas pela empresa
O GitHub bloqueia a instalação de apps em contas gerenciadas pela empresa (o GitHub chama isso de Enterprise Managed Users, ou EMU). Somente uma organização pode instalar apps. Sem uma organização, clicar em Install no GitHub redireciona você de volta à página do app Jamdesk. O cadastro no Jamdesk mostra "Your organization manages this GitHub account".
Nomes de usuário gerenciados terminam em sublinhado e um código da empresa, como jsmith_acme. O GitHub explica as limitações na página sobre contas de usuário gerenciadas.
Resolva com uma destas opções.
- Peça a um proprietário da empresa para criar uma organização na aba Organizations da sua empresa. Peça também que permita que você crie repositórios nela.
- Transfira seu repositório de documentação 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 Install GitHub App nas configurações do projeto). No GitHub, escolha a organização, selecione Only select repositories, marque seu repositório e instale.
Se o GitHub mostrar Request em vez de Install, um proprietário da organização recebe um e-mail para aprovar. Clique novamente no botão do Jamdesk depois que ele aprovar.
Use esta opção quando sua empresa não pode adicionar uma organização. Confirme antes com o administrador do GitHub. A documentação ficará fora do GitHub da sua 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 da sua documentação para ele. O GitHub não consegue transferir repositórios para fora de uma empresa gerenciada.
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 peça o login da sua conta pessoal.
- No Jamdesk, clique em Connect an existing repository (ou 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. Cada editor da documentação precisa de uma conta pessoal do GitHub. Adicione-os ao repositório como colaboradores.
Repositório não aparece
Se 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ção:
- Um administrador da organização deve 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. Autorize o Jamdesk novamente, se necessário.
Builds não são acionados
Se os pushes não disparam builds:
- Acesse seu repositório no GitHub
- Abra Settings → Webhooks
- Encontre o webhook do Jamdesk
- Verifique "Recent Deliveries" para ver erros
Os builds só são disparados no branch configurado. Confira em Settings no Jamdesk.
Se o build aparecer como falho com uma mensagem informando que quem fez o push não é membro, convide essa pessoa em Configurações do projeto → Membros ou peça que ela vincule a conta do GitHub. Consulte Os builds não são disparados.
- Acesse as Settings do projeto no Jamdesk
- Clique em Re-sync GitHub
Erros de webhook
404 Not Found
Não foi possível acessar o endpoint do webhook.
Solução: sincronize novamente a conexão com o GitHub nas configurações do projeto.
401 Unauthorized
A autenticação falhou.
Solução:
- Acesse as configurações da sua conta do GitHub
- Abra Applications → Authorized OAuth Apps
- Revogue o Jamdesk
- Autorize novamente nas configurações do Jamdesk
500 Server Error
Problema temporário no Jamdesk.
Solução: aguarde alguns minutos e envie o push novamente, ou dispare 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 com branches
Build na branch errada
Verifique o branch configurado em Settings → Repository.
Branch renomeada ou excluída
Atualize a configuração de branch para corresponder ao novo nome.
