Skip to main content
O conector GitHub lê uma organização do GitHub pela API REST: repositórios, issues, pull requests, membros e times viram tabelas no Data Catalog, e os arquivos de documentação de cada repositório viram documentos no Knowledge. Cada item carrega a permissão do repositório de onde veio.

​
Capacidades

  • Data Catalog. Cinco tabelas limpas, uma por recurso de registro: repositórios, issues, pull requests, membros e times.
  • Memory. O conector traz um mapeamento de ontologia em que membros, times, repositórios, issues e pull requests viram entidades, ligadas por autoria, responsável, repositório e hierarquia de times.
  • Knowledge. Os arquivos elegíveis do branch padrão de cada repositório (Markdown, reStructuredText, texto, CSV, PDF e Word) são enviados como documentos, com a permissão do repositório.
  • Permissão da fonte. A lista de quem pode ler cada repositório é lida a cada sincronização e aplicada aos repositórios, issues, pull requests e arquivos dele.

​
Recursos disponíveis

repositories fica sempre ligado. A permissão de issues, pull requests e arquivos é calculada a partir dele, então desligá-lo quebraria o controle de acesso. members e teams não têm permissão por item: quem pode usar o conector vê as duas listas, como no próprio GitHub, onde qualquer membro da organização vê membros e times.

​
Permissões (ACL)

O conector lê a permissão de cada item na fonte e a guarda junto com o dado. Em Comportamento dos dados, você escolhe entre dois modos: No modo “Espelhar a fonte”, marque Exigir login na fonte como prova de identidade. O GitHub identifica cada pessoa por um id próprio, não pelo e-mail, então a Strattum só reconhece quem se autenticou no GitHub.

​
Como a fonte define acesso

No GitHub, o menor nível de permissão de leitura é o repositório. Quem pode ler um repositório lê as issues, os pull requests e os arquivos dele. O acesso vem de dois lugares: pessoas adicionadas como colaboradoras do repositório e times que receberam o repositório.

​
Como a Strattum traduz o acesso

Para cada repositório, o conector soma os dois eixos: A mesma lista vale para o repositório e para todas as issues, pull requests e arquivos dele. Os principais usam o id numérico, e nunca o login ou o slug, porque login e slug podem ser renomeados no GitHub. A conta do GitHub não é deduzida pelo e-mail. Para o usuário ser reconhecido, marque Exigir login na fonte como prova de identidade no Console. No vínculo, a Strattum confirma a conta pelo e-mail primário verificado no GitHub e confere que a pessoa é membro da organização configurada. A participação em times é lida à parte, time por time, e associada às contas vinculadas.

​
Quando a identidade não é encontrada

No modo “Espelhar a fonte”, quem não vinculou a conta do GitHub não vê repositórios, issues, pull requests nem arquivos. O item continua visível para quem tem acesso a ele na fonte e já vinculou a conta. Um colaborador que o GitHub devolve sem id é descartado da lista e fica registrado no log da sincronização.

​
Quando a permissão é atualizada

A lista de acesso de cada repositório é relida a cada sincronização. Quando ela muda, o conector atualiza a permissão das issues e dos pull requests daquele repositório no mesmo sync, mesmo que nenhum item tenha sido editado. A participação das pessoas em times é atualizada por uma rotina própria, a cada 10 minutos por padrão. Os arquivos são a exceção: um repositório sem commit novo no branch padrão não é relido, e os arquivos dele mantêm a permissão da última vez em que foram lidos. Essa limitação está listada em “Limitações conhecidas”.

​
Pré-requisitos

  • Uma organização no GitHub. O conector lê uma organização por instância.
  • Uma conta que seja membro da organização e tenha papel write, maintain ou admin em cada repositório que você quer sincronizar. O GitHub exige esse papel para listar colaboradores, e nenhuma permissão do token substitui isso.
  • Um fine-grained personal access token dessa conta, com as permissões da tabela abaixo.
  • Se a organização exige aprovação de tokens, um owner da organização para aprovar o token.
  • Para o modo “Espelhar a fonte” com vínculo de conta: um OAuth App no GitHub, de onde saem o Client ID e o Client Secret.

​
Autenticação e escopos

O conector usa um fine-grained personal access token, enviado como Authorization: Bearer. Todas as permissões são de leitura. Members é uma permissão de organização, diferente das outras, que são de repositório. Um token sem ela conecta, lista repositórios e issues, e falha depois, ao ler times e permissões.
1

Abra a criação de token

No GitHub, clique na sua foto de perfil e acesse Settings > Developer settings > Personal access tokens > Fine-grained tokens. Clique em Generate new token. O endereço direto é github.com/settings/personal-access-tokens/new.
2

Escolha a organização

Preencha Token name e Expiration. Em Resource owner, selecione a organização que o conector vai ler.
3

Escolha os repositórios

Em Repository access, escolha All repositories ou Only select repositories. Os repositórios fora da seleção são pulados na sincronização.
4

Conceda as permissões

Em Permissions, conceda leitura nas permissões de repositório Metadata, Contents, Issues e Pull requests, e na permissão de organização Members.
5

Gere e aprove o token

Clique em Generate token e copie o valor, que começa com github_pat_. Se a organização exige aprovação, o token fica pendente até um owner aprovar, e até lá não abre repositórios privados.

​
Configuração no Console

1

Preencha a conexão

Nome do Conector (Opcional): um nome para identificar esta instância.Organização do GitHub (Obrigatório): o slug da organização, o mesmo que aparece na URL, como minha-organizacao em github.com/minha-organizacao. Aceita só letras, números e hífens simples.Personal Access Token (fine-grained) (Obrigatório): o token gerado na seção anterior.Clique em Testar Conexão. O Console só avança depois de um teste bem-sucedido. O teste pode passar com ressalvas, listadas em Conectado, com ressalvas, como repositórios que o token não abre.
2

Escolha os recursos

Repositórios (Obrigatório): fica sempre ligado.Arquivos de repositório, Issues, Pull requests, Membros da organização e Times (Opcional): ligue os que quiser sincronizar.Sincronização incremental (Opcional): aparece em Repositórios, Issues e Pull requests. Desligado, o recurso é relido inteiro a cada sincronização.
3

Defina a frequência

Frequência de sincronização (Obrigatório): o recomendado é A cada 2h (recomendado). Também há opções prontas, de 10 minutos a semanal, e Personalizado, para informar uma Expressão Cron. Os horários são em UTC.
4

Configure acesso e visibilidade

Quem pode usar este conector (Obrigatório): “Todos os usuários” ou “Apenas times específicos”. Na segunda opção, selecione os Times com acesso.Comportamento dos dados (Obrigatório): “Aberto” ou “Espelhar a fonte”.Exigir login na fonte como prova de identidade (Quando selecionado “Espelhar a fonte”): marque para que cada usuário vincule a conta do GitHub.URL de autenticação, Client ID e Client Secret (Quando selecionado o login na fonte, obrigatórios): os dados do OAuth App. No GitHub, a URL é sempre https://github.com/login/oauth/authorize.Escopos (Opcional): o conector pede user:email quando o campo fica vazio.
5

Revise e crie

Confira o resumo e clique para criar o conector.
Os arquivos só chegam ao Knowledge quando um contexto do Knowledge está ligado a este conector. Sem essa ligação, o Console avisa: “Nenhum contexto do Knowledge está ligado a este conector.”

​
Como a sincronização funciona

O agendamento recomendado roda a cada 2 horas. A cada execução, o conector testa o token em GET /user e para a sincronização se a chamada falhar. Repositórios, issues e pull requests. Todas as listagens seguem o link rel="next" do cabeçalho Link, com 100 itens por página. Em full refresh, cada recurso é lido inteiro e substitui a tabela anterior, então itens apagados no GitHub somem. Em incremental:
  • issues usa o filtro since da própria API, a partir da última data de atualização lida, com 1 segundo de sobreposição.
  • pull_requests e repositories não têm filtro de data na API. O conector lê do mais recente para o mais antigo e para ao chegar no último updated_at já lido.
  • Os itens novos ou alterados são mesclados na tabela. Item apagado no GitHub continua na tabela.
Membros e times. A API não devolve data de atualização, então as duas listas são lidas inteiras a cada sincronização. Arquivos. O conector guarda o último commit lido do branch padrão de cada repositório:
  1. Se o commit não mudou, o repositório é pulado.
  2. Se mudou, o conector compara os dois commits e baixa só os arquivos alterados.
  3. Se a comparação não é conclusiva (mais de 300 arquivos alterados, histórico reescrito ou nenhum commit anterior), o conector lê a árvore inteira do repositório.
Um arquivo é elegível quando tem extensão .md, .mdx, .rst, .txt, .csv, .pdf ou .docx, não está em caminhos como node_modules/, vendor/ ou dist/, e tem até 1 MB (texto) ou 10 MB (PDF e Word). PDF e Word passam pelo leitor de documentos da plataforma. Arquivo que não é texto UTF-8 válido é ignorado. Arquivo apagado no GitHub só sai do Knowledge numa sincronização completa, em que todos os repositórios são lidos de novo. Numa execução comum, ele permanece. Repositórios fora do alcance do token. A organização lista todos os repositórios, inclusive os que um token com acesso a repositórios selecionados não abre. Esses repositórios são pulados, sem derrubar a sincronização, e aparecem no log da execução.

​
API da fonte

O conector usa a API REST do GitHub em https://api.github.com, na versão 2022-11-28. Rate limits. Limite da API: um usuário autenticado tem 5.000 requisições por hora, ou 15.000 no GitHub Enterprise Cloud. O token é pessoal, então esse limite é dividido com o resto do uso da conta dona do token. Há também limites secundários: até 100 requisições simultâneas e até 900 pontos por minuto nos endpoints REST. Estourar qualquer um devolve 403 ou 429 (documentação). Comportamento do conector: as requisições são feitas uma de cada vez, nunca em paralelo. Ao receber 403 ou 429 de limite, o conector espera o tempo de retry-after; sem ele, espera até x-ratelimit-reset quando x-ratelimit-remaining é 0; sem nenhum dos dois, espera 1 minuto e dobra a espera a cada nova tentativa. Cada espera tem no máximo 15 minutos, e uma requisição aceita até 4 esperas antes de falhar. Um 403 sem sinal de limite é tratado como falta de permissão e não é repetido. Referência oficial: https://docs.github.com/en/rest?apiVersion=2022-11-28

​
Limitações conhecidas

  • Não sincroniza commits, comentários de issues e pull requests, wikis, discussions nem releases.
  • Só lê o branch padrão de cada repositório. Arquivos de outros branches não chegam ao Knowledge.
  • Arquivos de código-fonte e configuração (por exemplo .py, .ts, .json, .yaml) não são enviados ao Knowledge.
  • Quando a permissão de um repositório muda sem commit novo no branch padrão, os arquivos dele no Knowledge mantêm a permissão antiga até o próximo commit ou a próxima sincronização completa.
  • Arquivo apagado no GitHub continua no Knowledge até uma sincronização completa.
  • Em incremental, issue, pull request ou repositório apagado no GitHub continua no Data Catalog. Use full refresh para remover.
  • No modo “Espelhar a fonte”, o conteúdo dos repositórios só aparece para quem vinculou a conta do GitHub.
  • Se você indexar issues no Knowledge pelo modelo de indexação da tabela do Data Catalog, as issues indexadas não carregam a permissão do repositório e não aparecem nas buscas dos usuários.
  • A autenticação é só por fine-grained personal access token. GitHub App não é suportado. O token pertence a uma pessoa e expira: se ela sair da organização ou revogar o token, o conector para.
  • Uma instância lê uma única organização.

​
Troubleshooting

​
Próximos passos

Data Catalog

Encontre as tabelas de repositórios, issues, pull requests, membros e times.

Knowledge

Ligue um contexto a este conector para buscar nos arquivos dos repositórios.
Para rodar o conector fora do Console, defina as duas variáveis no .env (veja Desenvolvimento local):