Jamdesk Documentation logo

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ãoFinalidadeEscopoObrigatória?
GitHub AppAcesso aos repositórios e webhooksPor projetoSim
Conta pessoalIdentidade do usuário e atribuiçãoPor usuárioRecomendada

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)

1
Entre com o GitHub

Autorize a Jamdesk a criar um repositório na sua conta ou organização.

2
Escolha onde criá-lo

Escolha sua conta pessoal ou uma organização. A Jamdesk cria um novo repositório preenchido com documentação inicial.

3
Instale o GitHub App

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.

4
Envios disparam builds

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

1
Acesse as configurações do usuário

Clique no seu avatar no canto superior direito e selecione User Settings.

2
Encontre a seção GitHub Account

Role até o cartão GitHub Account.

4
Confirme a conexão

Seu nome de usuário do GitHub aparece no seu perfil da Jamdesk.

Como elas funcionam juntas

Pense neles como duas chaves separadas:

ChaveAbrePertence a
GitHub AppAcesso aos repositóriosProjeto/Organização
Vínculo pessoalSua identidadeUsuário individual

Exemplo de equipe

Uma equipe de 3 desenvolvedores trabalha na documentação da empresa:

  1. O administrador instala o GitHub App na organização
  2. O administrador cria um projeto na Jamdesk conectado ao repositório de documentação
  3. 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:

  1. Acesse GitHub Settings → Applications → Installed GitHub Apps
  2. Encontre "Jamdesk" e clique em Configure
  3. Role para baixo e clique em Uninstall

Referência rápida

AçãoLocalEscopoReversível?
Desconectar GitHubProject Settings → Git RepositoryProjeto únicoSim - reconecte quando quiser
Desvincular GitHubUser Settings → GitHub AccountSua contaSim - vincule novamente quando quiser
Desinstalar GitHub AppGitHub SettingsTodos os projetosSim - 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:

1
Encontre Repository access

Role até a seção Repository access na página de configurações do GitHub.

2
Ative o botão Save

Se o botão Save estiver desabilitado (em cinza), mude de "All repositories" para "Only select repositories" e depois volte.

3
Clique em Save

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"

  1. Verifique se o repositório está conectado em Project Settings → Git Repository
  2. Confirme que você está enviando para a branch configurada
  3. 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.

Artigos relacionados

Criar um projeto

Configure seu primeiro projeto de documentação

Solução de problemas de builds

Problemas comuns de build e soluções