Integração com GitHub
A Jamdesk usa duas conexões com o GitHub: um GitHub App para acesso aos repositórios e um vínculo da conta pessoal para atribuição de builds.
A Jamdesk usa duas conexões separadas com o GitHub, com funções diferentes.
Resumo: O GitHub App dá à Jamdesk acesso ao seu repositório. Vincular sua conta pessoal atribui seus commits a você.
Projetos do Bitbucket Cloud funcionam de outra forma. 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 aos repositórios e webhooks | Por projeto | Sim |
| Conta pessoal | Identidade do usuário e atribuição | Por usuário | Recomendada |
GitHub App (nível do projeto)
O GitHub App da Jamdesk é instalado na sua conta ou organização do GitHub. Ele dá à Jamdesk acesso aos repositórios que você escolher.
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 (push)
- Informa o status do build: mostra o status da implantação nos commits
Por que você precisa dele
Sem o GitHub App instalado, a Jamdesk não consegue:
- Acessar seu repositório para gerar a documentação
- Implantar automaticamente quando você enviar alterações
- Mostrar o status do build nos commits do GitHub
Como funciona
A configuração do projeto guia você na conexão com o GitHub. Escolha um dos dois caminhos.
Criar um repositório inicial de documentação (padrão para novos projetos)
Autorize a Jamdesk a criar um repositório na sua conta ou organização.
Escolha sua conta pessoal ou uma organização. A Jamdesk cria um novo repositório preenchido com documentação inicial.
Instale o GitHub App da Jamdesk (ou conceda acesso ao novo repositório). O app faz o build e a implantação automática da sua documentação.
Cada envio para a branch configurada dispara automaticamente uma implantação. Personalize a documentação inicial quando quiser.
Conectar um repositório existente
Instale o GitHub App da Jamdesk e conceda a ele acesso ao seu repositório de documentação. Depois, escolha o repositório e a branch na Jamdesk em Project Settings → Git Repository. O restante funciona da mesma forma.
Um app, vários projetos
Uma única instalação do GitHub App pode atender a vários projetos da Jamdesk:
- Instale o app uma vez na sua conta ou organização
- Conecte repositórios diferentes a projetos diferentes da Jamdesk
- Cada projeto tem sua própria configuração de branch e caminho
Um administrador da organização instala o GitHub App uma única vez. Depois, qualquer membro da equipe pode criar projetos da Jamdesk a partir de 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 da Jamdesk. Isso é separado do GitHub App.
O que ela faz
- Identifica você: associa seu nome de usuário do GitHub à sua conta da Jamdesk
- Atribui builds: mostra quem disparou cada implantação
- Visibilidade para a equipe: os colegas veem quem fez alterações
Por que você precisa dela
A Jamdesk precisa associar cada envio a um usuário. Sem a sua conta vinculada:
- A Jamdesk recorre à correspondência pelo endereço de e-mail
- Se o e-mail do seu commit no Git for diferente do seu e-mail na Jamdesk, a atribuição falha
- O histórico de builds pode mostrar "Usuário desconhecido" nos seus commits
Problema comum: o Git usa um e-mail pessoal. Sua conta da Jamdesk usa um e-mail corporativo. Vincule sua conta do GitHub para corrigir a atribuição.
Verificar seu e-mail do Git
git config user.email
git config --global user.email "you@company.com"
Defina-o como o e-mail da sua conta da Jamdesk. Um e-mail diferente aparece como "Usuário desconhecido" 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.
Abre-se uma janela pop-up do GitHub. Autorize a Jamdesk a ler seu perfil.
Seu nome de usuário do GitHub aparece no seu perfil da Jamdesk.
Como elas funcionam juntas
Pense neles 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
Uma equipe de 3 desenvolvedores trabalha na documentação da empresa:
- O administrador instala o GitHub App na organização
- O administrador cria um projeto na Jamdesk conectado ao repositório de documentação
- Cada desenvolvedor vincula sua conta pessoal
Agora, quando qualquer desenvolvedor enviar alterações:
- O GitHub App permite que a Jamdesk leia o repositório e faça o build
- O vínculo pessoal identifica quem disparou o build
Exemplo de desenvolvedor solo
Desenvolvedores individuais também precisam das duas conexões:
- GitHub App: conecta seu repositório à Jamdesk
- Vínculo pessoal: mostra seu nome nos seus commits no histórico de builds
Desconectar e desvincular
Cada ação remove uma parte diferente do acesso.
Desconectar o GitHub (Project Settings)
O que faz: Remove a conexão com o repositório de um único projeto da Jamdesk.
Efeitos:
- As implantações automáticas param para esse projeto
- O GitHub App continua instalado no GitHub
- Outros projetos da Jamdesk não são afetados
- Seu vínculo com a conta pessoal não é afetado
Quando usar: Você quer conectar um repositório diferente ou parar as implantações temporariamente.
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 da Jamdesk.
Efeitos:
- Seu nome de usuário do GitHub deixa de aparecer no seu perfil
- A atribuição de builds passa 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 vincular novamente: Acesse User Settings → GitHub Account → Link GitHub Account.
Desinstalar o GitHub App (no GitHub)
O que faz: Remove o acesso da Jamdesk à sua conta do GitHub.
Efeitos:
- Todos os projetos da Jamdesk que usam esta instalação perdem o acesso
- As implantações automáticas param para todos os projetos afetados
- Os webhooks são removidos
- Os vínculos das contas pessoais não são afetados
Desinstale o GitHub App somente se quiser remover o acesso da Jamdesk de todos os repositórios. Isso afeta todos os projetos da 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 GitHub | Project Settings → Git Repository | Projeto único | Sim - reconecte quando quiser |
| Desvincular GitHub | User Settings → GitHub Account | Sua conta | Sim - vincule novamente quando quiser |
| Desinstalar GitHub App | GitHub Settings | Todos os projetos | Sim - reinstale |
Solução de problemas
"Already have Jamdesk installed?"
Se você já instalou o GitHub App da Jamdesk, "Install GitHub App" abre a página de configurações do GitHub em vez da página de instalação. Conclua a configuração ali:
Role até a seção Repository access na página de configurações do GitHub.
Se o botão Save estiver desabilitado (em cinza), mude de "All repositories" para "Only select repositories" e depois volte.
Clique no botão verde Save. A Jamdesk detecta a alteração e continua a configuração.
Pop-up bloqueado
Se a janela do GitHub não abrir, seu navegador pode tê-la bloqueado. Procure o ícone de bloqueador de pop-ups na barra de endereços, permita pop-ups da 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 a Jamdesk e adicione o repositório.
"Builds aren't triggering"
- Verifique se o repositório está conectado em Project Settings → Git Repository
- Confirme que você está enviando para a branch configurada
- Verifique a entrega dos webhooks nas configurações do repositório no GitHub
Se tudo estiver correto, a pessoa que enviou as alterações pode não ser membro do projeto. A Jamdesk só cria build de um envio feito por um membro do projeto. Ela identifica quem enviou pela conta do GitHub vinculada ou pelo e-mail do commit, quando ele corresponde ao e-mail com o qual a pessoa entra na Jamdesk.
Sem correspondência, o build aparece como falho, com o motivo. O dono do projeto recebe um e-mail, no máximo um por semana por pessoa. Um envio que não altera nada na sua pasta de documentação não envia e-mail.
Convide a pessoa em Project Settings → Members usando o e-mail dos commits dela. Ela precisa entrar na Jamdesk com esse e-mail para aceitar. Se ela já for membro, pode vincular a conta do GitHub em User Settings.
"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 a Jamdesk nas configurações da organização.
"GitHub keeps sending me back to the Jamdesk app page"
Sua empresa provavelmente gerencia sua conta do GitHub. O GitHub não permite que contas gerenciadas instalem apps em si mesmas. Consulte contas do GitHub gerenciadas pela empresa para a solução.
