Integração com GitHub
O Jamdesk usa duas conexões do GitHub: um GitHub App para acesso aos repositórios e um vínculo à conta pessoal para atribuir builds.
O Jamdesk usa duas conexões separadas do GitHub, cada uma com uma função diferente. Esta página explica o que cada conexão faz e quando você precisa dela.
TL;DR: O GitHub App dá ao Jamdesk acesso ao seu repositório. Vincular sua conta pessoal garante que seus commits sejam atribuídos a você.
Os projetos do Bitbucket Cloud funcionam de forma diferente: uma única autorização OAuth cobre o acesso ao repositório, o webhook e a atribuição de builds. Consulte Conectar Bitbucket.
Visão geral
| Conexão | Finalidade | Escopo | Obrigatória? |
|---|---|---|---|
| GitHub App | Acesso ao repositório e webhooks | Por projeto | Sim |
| Conta pessoal | Identidade e atribuição do usuário | Por usuário | Recomendável |
GitHub App (nível do projeto)
O GitHub App do Jamdesk é instalado na sua conta ou organização do GitHub. Ele concede ao Jamdesk permissão para acessar repositórios específicos.
O que ele faz
- Lê o conteúdo do repositório - Clona sua documentação para fazer o build
- Recebe webhooks - É notificado quando você envia alterações
- Informa o status do build - Mostra o status do deploy nos commits
Por que você precisa dele
Sem o GitHub App instalado, o Jamdesk não pode:
- Acessar seu repositório para fazer o build da documentação
- Fazer o deploy automaticamente quando você envia alterações
- Mostrar o status do build nos commits do GitHub
Como funciona
Ao configurar um projeto, o Jamdesk orienta você durante a conexão com o GitHub. Há dois caminhos.
Criar um repositório inicial de documentação (padrão para novos projetos)
Autorize o Jamdesk para que ele possa criar um repositório na sua conta ou organização.
Escolha sua conta pessoal ou uma organização. O Jamdesk cria um novo repositório preenchido previamente com a documentação inicial.
Instale o GitHub App do Jamdesk (ou conceda a ele acesso ao novo repositório) para que ele possa fazer o build e o deploy automático da sua documentação.
Cada push para sua branch configurada aciona automaticamente um deploy. Personalize a documentação inicial quando estiver pronto.
Conectar um repositório existente
Já tem um repositório de documentação? Instale o GitHub App do Jamdesk, conceda acesso a esse repositório e escolha o repositório e a branch no Jamdesk, em Project Settings → Git Repository. A partir daí, o funcionamento é o mesmo.
Um app, vários projetos
Uma única instalação do GitHub App pode atender a vários projetos do Jamdesk:
- Instale o app uma vez na sua conta ou organização
- Conecte repositórios diferentes a projetos diferentes do Jamdesk
- Cada projeto tem sua própria configuração de branch e caminho
Para organizações, um administrador só precisa instalar o GitHub App uma vez. Depois, qualquer membro da equipe pode criar projetos do Jamdesk usando os repositórios aos quais o app tem acesso.
Conta pessoal do GitHub (nível do usuário)
Vincular sua conta pessoal do GitHub associa sua identidade do GitHub ao seu perfil do Jamdesk. Isso é separado do GitHub App.
O que ela faz
- Identifica você - Associa seu nome de usuário do GitHub à sua conta do Jamdesk
- Atribui builds - Mostra quem acionou cada deploy
- Visibilidade da equipe - Outros membros da equipe podem ver quem fez as alterações
Por que você precisa dela
Quando você envia alterações para o GitHub, o Jamdesk precisa determinar qual usuário acionou o build. Sem sua conta vinculada:
- O Jamdesk recorre à correspondência pelo endereço de e-mail
- Se o e-mail do seu commit do Git for diferente do e-mail do Jamdesk, a atribuição falhará
- O histórico de builds pode mostrar "Unknown user" para seus commits
Problema comum: seu Git está configurado com um e-mail pessoal, mas você se cadastrou no Jamdesk com um e-mail de trabalho. Vincule sua conta do GitHub para garantir a atribuição correta.
Verificar seu e-mail do Git
git config user.email
git config --global user.email "you@company.com"Use o mesmo e-mail que aparece na sua conta do Jamdesk para evitar a atribuição como "Unknown user" no histórico de builds.
Como vincular sua conta
Clique no seu avatar no canto superior direito e selecione User Settings.
Role até o cartão GitHub Account.
Uma janela pop-up será aberta no GitHub. Autorize o Jamdesk a ler seu perfil.
Seu nome de usuário do GitHub aparecerá no seu perfil do Jamdesk.
Como elas funcionam juntas
Pense nelas como duas chaves separadas:
| Chave | Abre | Pertence a |
|---|---|---|
| GitHub App | Acesso aos repositórios | Projeto/organização |
| Vínculo pessoal | Sua identidade | Usuário individual |
Exemplo de equipe
Considere uma equipe com 3 desenvolvedores trabalhando na documentação da empresa:
- O administrador instala o GitHub App na organização
- O administrador cria um projeto do Jamdesk conectado ao repositório de documentação
- Cada desenvolvedor vincula sua conta pessoal
Agora, quando qualquer desenvolvedor fizer um push:
- O GitHub App permite que o Jamdesk leia o repositório e faça o build
- O vínculo pessoal identifica quem acionou o build
Exemplo de desenvolvedor solo
Mesmo trabalhando sozinho, as duas conexões têm finalidades diferentes:
- GitHub App - Conecta seu repositório ao Jamdesk
- Vínculo pessoal - Garante que seus commits mostrem seu nome no histórico de builds
Desconectar e desvincular
Cada ação remove uma parte diferente do acesso. Veja o que cada uma afeta.
Desconectar o GitHub (Project Settings)
O que faz: remove a conexão com o repositório de um único projeto do Jamdesk.
Efeitos:
- Os deploys automáticos são interrompidos para esse projeto
- O GitHub App continua instalado no GitHub
- Os outros projetos do Jamdesk não são afetados
- O vínculo com sua conta pessoal não é afetado
Quando usar: você quer conectar outro repositório ou interromper temporariamente os deploys.
Como reconectar: acesse Project Settings → Git Repository e selecione um repositório.
Desvincular o GitHub (User Settings)
O que faz: remove sua identidade do GitHub do seu perfil do Jamdesk.
Efeitos:
- Seu nome de usuário do GitHub não aparece mais no seu perfil
- A atribuição de builds volta a usar a correspondência por e-mail
- Todas as conexões com repositórios permanecem intactas
- O GitHub App continua instalado
Quando usar: você quer vincular outra conta do GitHub ou remover a conexão.
Como revincular: acesse User Settings → GitHub Account → Link GitHub Account.
Desinstalar o GitHub App (no GitHub)
O que faz: remove completamente o acesso do Jamdesk à sua conta do GitHub.
Efeitos:
- Todos os projetos do Jamdesk que usam essa instalação perdem o acesso
- Os deploys automáticos são interrompidos para todos os projetos afetados
- Os webhooks são removidos
- Os vínculos com contas pessoais não são afetados
Desinstale o GitHub App somente se quiser remover o acesso do Jamdesk de todos os seus repositórios. Isso afeta todos os projetos do Jamdesk conectados à sua conta do GitHub.
Como desinstalar:
- Acesse GitHub Settings → Applications → Installed GitHub Apps
- Encontre "Jamdesk" e clique em Configure
- Role para baixo e clique em Uninstall
Referência rápida
| Ação | Local | Escopo | Reversível? |
|---|---|---|---|
| Desconectar o GitHub | Project Settings → Git Repository | Um único projeto | Sim - reconecte quando quiser |
| Desvincular o GitHub | User Settings → GitHub Account | Sua conta | Sim - revincule quando quiser |
| Desinstalar o GitHub App | GitHub Settings | Todos os projetos | Sim - reinstale |
Solução de problemas
"Already have Jamdesk installed?"
Se você já instalou o GitHub App do Jamdesk, clicar em "Install GitHub App" levará você à página de configurações do GitHub em vez da página de instalação. Isso é normal! Veja como concluir a configuração:
Role até a seção Repository access na página de configurações do GitHub.
Se o botão Save estiver desativado (acinzentado), mude de "All repositories" para "Only select repositories" e depois volte.
Clique no botão verde Save. O Jamdesk detectará a alteração e continuará a configuração.
Pop-up bloqueado
Se o pop-up do GitHub não abrir, seu navegador pode tê-lo bloqueado. Procure um ícone de bloqueador de pop-ups na barra de endereço, permita pop-ups do Jamdesk e clique em Try Again.
"My builds show 'Unknown user'"
Sua conta pessoal do GitHub não está vinculada. Acesse User Settings → Link GitHub Account.
"Repository not showing up"
O GitHub App não tem acesso a esse repositório. Acesse GitHub Settings, encontre o Jamdesk e adicione o repositório.
"Builds aren't triggering"
- Verifique se o repositório está conectado em Project Settings → Git Repository
- Confirme se você está fazendo push para a branch configurada
- Verifique a entrega do webhook nas configurações do repositório no GitHub
"I can't access organization repositories"
Um administrador da organização precisa aprovar a instalação do GitHub App. Peça ao administrador para instalar ou aprovar o Jamdesk nas configurações da organização.
"GitHub keeps sending me back to the Jamdesk app page"
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.