Jamdesk Documentation logo

Conectar GitHub

Conecte seu repositório do GitHub ao Jamdesk para implantações automáticas a cada push. Cobre instalação do app, seleção de repositório e configuração de branch.

O Jamdesk implanta sua documentação automaticamente quando você faz push para o GitHub.

As capturas de tela mostram a interface em inglês.

Para entender como o GitHub App e a vinculação de conta pessoal funcionam juntos, consulte Entendendo a integração com o GitHub.

Documentação no Bitbucket Cloud? Consulte Conectar Bitbucket. Cada projeto se conecta a um provedor. Sem conta no GitHub? Consulte Documentação sem GitHub.

Instalação do GitHub App

O Jamdesk solicita que você instale o GitHub App do Jamdesk na primeira vez que fizer login. O app concede:

  • Acesso ao repositório: ler o conteúdo da sua documentação
  • Webhooks: acionar builds a cada push
  • Status de commit: mostrar o status do build nos commits

Permissões

O GitHub App do Jamdesk solicita estas permissões:

PermissãoFinalidade
Conteúdo do repositório (leitura e escrita)Clonar e ler seus arquivos de documentação. As gravações acontecem somente quando você salva no editor do dashboard, aceita sugestões do Fix with AI ou ativa a tradução
Metadados (leitura)Listar repositórios e branches
WebhooksReceber notificações de push

O Jamdesk acessa apenas os repositórios para os quais você concedeu acesso explicitamente. Altere o acesso a qualquer momento nas configurações do seu GitHub.

Conectar um repositório

1
Selecionar repositório

Clique em Connect Repository ao criar ou editar um projeto.

Escolha entre os repositórios em que o GitHub App está instalado.

2
Escolher branch

Selecione a branch a ser implantada:

  • main ou master: mais comum para documentação de produção
  • docs: se você mantém a documentação em uma branch separada
  • Qualquer branch: para implantações de preview
3
Especificar o caminho da documentação

Se o seu docs.json não estiver na raiz do repositório, especifique o caminho:

docs/           # Docs in a subdirectory
packages/docs/  # Monorepo with docs package

Deixe em branco se o docs.json estiver na raiz.

O painel do projeto então mostra o repositório e a branch vinculados:

Dashboard showing GitHub repository connected with Linked status badge, repository name, and branch

Deploys automáticos

Cada push para a branch configurada aciona um build:

git add .
git commit -m "Update API documentation"
git push origin main

Os builds normalmente terminam em 30 a 90 segundos. Veja o status no painel ou no commit do GitHub.

Alterar repositórios

Para conectar um repositório diferente:

  1. Acesse Settings → Repository
  2. Clique em Change Repository
  3. Selecione o novo repositório e a branch

Trocar de repositório pode afetar sua documentação ao vivo. O novo repositório deve conter uma configuração válida do Jamdesk.

Gerenciar o acesso do GitHub App

Controle a quais repositórios o Jamdesk pode acessar:

  1. Acesse github.com/settings/installations
  2. Encontre Jamdesk na lista
  3. Clique em Configure
  4. Em "Repository access", selecione repositórios específicos ou todos

Repositórios de organizações

Um administrador da organização deve aprovar a instalação do GitHub App para repositórios de organizações:

  1. Solicite a instalação no seu dashboard do Jamdesk
  2. Um administrador recebe uma notificação no GitHub
  3. Os repositórios da organização aparecem no seletor de repositórios após a aprovação

Vincular sua conta pessoal

Vincule sua conta pessoal do GitHub em User Settings para uma atribuição confiável dos builds:

  1. Clique no seu avatar → User Settings
  2. Encontre a seção GitHub Account
  3. Clique em Link GitHub Account

Esse vínculo é separado do GitHub App. Ele atribui seus commits a você. Saiba mais.

Solução de problemas

Repositório não aparece

  • Verifique se o GitHub App está instalado no repositório
  • Para repositórios de organizações, confirme que um administrador aprovou o acesso
  • Atualize a lista de repositórios no dashboard

O GitHub continua redirecionando você para a página do app do Jamdesk

Sua empresa provavelmente gerencia sua conta do GitHub. O GitHub não permite que essas contas instalem apps por conta própria. Consulte contas do GitHub gerenciadas pela empresa para resolver.

Usar uma conta do GitHub que outra conta do Jamdesk já utiliza

A lista de repositórios mostra uma mensagem que começa com:

Another Jamdesk account already uses this GitHub account.

Isso significa que um projeto de outra conta do Jamdesk já usa o GitHub App do Jamdesk nessa conta do GitHub. Normalmente, um colega configurou o Jamdesk primeiro, ou você está conectado a uma segunda conta do Jamdesk.

Para usar os repositórios dessa conta:

  1. Clique em Verify on GitHub.
  2. Faça login no GitHub com um usuário que possa fazer push no repositório.
  3. Escolha o repositório na lista.

Verify on GitHub vincula o usuário do GitHub com o qual você fez login à sua conta do Jamdesk, da mesma forma que User Settings faz. Se o seu navegador já estiver conectado ao GitHub com outra pessoa, saia do GitHub primeiro.

A lista mostra apenas os repositórios para os quais o seu usuário do GitHub pode fazer push. A verificação dura uma hora, então escolha o repositório logo após verificar. Se o Jamdesk informar que o GitHub não mostrou nenhuma instalação que você possa usar, confira se fez login com o usuário correto do GitHub. Ou peça a um proprietário da conta do GitHub que conceda acesso ao repositório.

Para trabalhar no mesmo projeto, peça ao proprietário dele que convide você.

Os builds não são acionados

  • Verifique se o webhook está ativo nas configurações do repositório
  • Confirme que você está fazendo push para a branch configurada
  • Procure erros de entrega de webhook no GitHub

Erros de permissão negada

  • Autorize novamente o GitHub App nas suas configurações do GitHub
  • Confirme que o GitHub App do Jamdesk pode acessar o repositório

Para uma solução de problemas mais detalhada, consulte Entendendo a integração com o GitHub.

O que fazer em seguida?

Criar um projeto

Configure um novo projeto Jamdesk

Estrutura de diretórios

Organize sua documentação para escalar