> ## Documentation Index > Fetch the complete documentation index at: https://strattumai.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # GitHub > Sincroniza repositórios, issues, pull requests, membros e times de uma organização GitHub para o Data Catalog e o Memory, e envia os arquivos de documentação dos repositórios para o Knowledge. 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. | | | | - | - | | **Status** | Beta | | **Conteúdo** | Registros e documentos | | **Autenticação** | Fine-grained personal access token | | **Permissões** | Por item | | **Sincronização** | Incremental e full refresh, por recurso | | **Última revisão** | 24/09/2026 | ## 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 | Recurso | O que contém | Carga | Cursor | Destino | Permissão por item | | - | - | - | - | - | - | | `repositories` | Repositórios da organização: nome, visibilidade, descrição, branch padrão, linguagem, tópicos, contadores e datas | Full refresh (padrão) ou incremental | `updated_at` | Catálogo e Memory | Sim | | `issues` | Issues de todos os repositórios, sem os pull requests: título, corpo, estado, autor, responsáveis, labels, milestone e datas | Full refresh (padrão) ou incremental | `updated_at` | Catálogo e Memory | Sim | | `pull_requests` | Pull requests de todos os repositórios: título, corpo, estado, rascunho, merge, branches de origem e destino, revisores pedidos e datas | Full refresh (padrão) ou incremental | `updated_at` | Catálogo e Memory | Sim | | `members` | Membros da organização: login, tipo de conta e e-mail, quando a pessoa o deixou público no perfil | Full refresh | Nenhum | Catálogo e Memory | Não | | `teams` | Times da organização: slug, nome, descrição, privacidade, permissão padrão e time pai | Full refresh | Nenhum | Catálogo e Memory | Não | | `repository_files` | Arquivos elegíveis do branch padrão de cada repositório, com caminho e conteúdo | Incremental por commit | Nenhum | Knowledge | Sim | `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: | Modo | Quem vê | | - | - | | Aberto | Quem puder usar este conector vê todos os registros. As permissões da fonte são ignoradas. | | Espelhar a fonte | Cada pessoa vê apenas os registros que a própria fonte libera para ela. | 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: | Eixo da fonte | Chamada | Principal gravado | | - | - | - | | Colaboradores diretos | `GET /repos/{owner}/{repo}/collaborators?affiliation=direct` | a pessoa, pelo id numérico da conta GitHub | | Times com acesso ao repositório | `GET /orgs/{org}/teams/{team_slug}/repos`, time por time | o time, pelo id numérico do time | 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. | Escopo ou permissão | Para quê | | - | - | | `Metadata` (read), repositório | Listar os repositórios da organização e os colaboradores de cada um | | `Contents` (read), repositório | Ler o branch padrão, comparar commits e baixar a árvore e os arquivos para `repository_files` | | `Issues` (read), repositório | Ler `issues` | | `Pull requests` (read), repositório | Ler `pull_requests` | | `Members` (read), organização | Ler `members` e `teams`, os repositórios de cada time e os membros de cada time | `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](https://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. > [!NOTE] > > 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`. | Método e caminho | Usado para | Recurso | | - | - | - | | `GET /user` | Testar o token | Nenhum | | `GET /orgs/{org}/repos` | Listar os repositórios da organização | `repositories` | | `GET /repos/{owner}/{repo}/issues` | Listar issues, com `state=all` | `issues` | | `GET /repos/{owner}/{repo}/pulls` | Listar pull requests, com `state=all` | `pull_requests` | | `GET /orgs/{org}/members` | Listar membros | `members` | | `GET /orgs/{org}/teams` | Listar times | `teams` | | `GET /repos/{owner}/{repo}/collaborators` | Ler os colaboradores diretos de cada repositório | Permissões | | `GET /orgs/{org}/teams/{team_slug}/repos` | Ler os repositórios de cada time | Permissões | | `GET /orgs/{org}/teams/{team_slug}/members` | Ler os membros de cada time, para o vínculo de conta | Permissões | | `GET /repos/{owner}/{repo}/branches/{branch}` | Ler o último commit do branch padrão | `repository_files` | | `GET /repos/{owner}/{repo}/compare/{basehead}` | Listar os arquivos alterados entre dois commits | `repository_files` | | `GET /repos/{owner}/{repo}/git/trees/{tree_sha}` | Ler a árvore inteira do repositório | `repository_files` | | `GET /repos/{owner}/{repo}/git/blobs/{file_sha}` | Baixar o conteúdo de um arquivo | `repository_files` | **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](https://docs.github.com/en/rest/using-the-rest-api/rate-limits-for-the-rest-api?apiVersion=2022-11-28)). 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](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 | Mensagem ou sintoma | Causa | O que fazer | | - | - | - | | "Token inválido ou expirado." | O token foi revogado, expirou ou foi copiado errado | Gere um novo fine-grained token e informe-o de novo no Console | | "Organização 'minha-organizacao' não encontrada no GitHub." | O slug está errado ou o token não tem acesso à organização | Confira o slug (o trecho depois de `github.com/`) e o **Resource owner** do token | | "Conectado, mas sem acesso à ACL da organização." | Falta `Members` (read) de organização, o token está pendente de aprovação ou a conta não tem o papel exigido | Ajuste as permissões do token, peça a um owner para aprovar e teste de novo | | "acl (collaborators): o dono do token precisa de papel write, maintain ou admin no repositório, além de Metadata: read." | A conta dona do token só tem leitura no repositório | Dê à conta papel write, maintain ou admin no repositório | | "Este token não abre pelo menos N repositórios que a organização lista" | O token tem acesso a repositórios selecionados | Nada, se for intencional. Para incluí-los, dê ao token acesso a eles | | "Nenhum repositório visível ao token" | O token não abre nenhum repositório da organização | Confira **Repository access** e a aprovação do token | | A sincronização falha com `github: HTTP 403 listing collaborators` ou `listing team_repos` | A permissão para ler colaboradores ou times foi recusada num repositório que o token abre | Siga a permissão indicada na mensagem: `Members` (read) de organização para times, papel write ou superior para colaboradores | | "Nenhum contexto do Knowledge está ligado a este conector." | Nenhum contexto do Knowledge usa este conector | Crie ou edite um contexto do Knowledge com este conector como fonte | | Um usuário não vê nada dos repositórios no modo "Espelhar a fonte" | A conta do GitHub dele não está vinculada, ou ele não tem acesso ao repositório na fonte | Peça ao usuário para vincular a conta e confira o acesso dele no GitHub | ## Próximos passos > **[Data Catalog](/data-catalog/overview.md)** > > Encontre as tabelas de repositórios, issues, pull requests, membros e times. > **[Knowledge](/knowledge/overview.md)** > > Ligue um contexto a este conector para buscar nos arquivos dos repositórios. > **Desenvolvimento local** > > Para rodar o conector fora do Console, defina as duas variáveis no `.env` (veja [Desenvolvimento local](/data-pipelines/local-development.md)): > > | Variável | Descrição | Exemplo | > | - | - | - | > | `GITHUB_ACCESS_TOKEN` | Fine-grained personal access token | `github_pat_11XXXXXXX...` | > | `GITHUB_ORG` | Slug da organização | `minha-organizacao` | > > ```bash theme={null} > GITHUB_ACCESS_TOKEN=github_pat_11XXXXXXX... > GITHUB_ORG=minha-organizacao > ``` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.