Você quer vincular seu workspace do Notion ao rastreador de issues do seu repositório GitHub para que novas issues apareçam automaticamente em um banco de dados do Notion. O Notion oferece uma integração nativa com o GitHub que sincroniza issues, pull requests e outros eventos em um banco de dados dedicado. Este artigo mostra como conectar sua conta do GitHub, selecionar um repositório e configurar a sincronização para que sua equipe possa gerenciar tarefas de desenvolvimento dentro do Notion. Você aprenderá a configurar a integração, mapear campos e evitar falhas comuns de sincronização.
Principais Pontos: Sincronizando o Notion com Issues do GitHub
- Configurações e Membros > Conexões > GitHub: Inicia a conexão OAuth entre seu workspace do Notion e sua conta do GitHub.
- Seleção do modelo de banco de dados do GitHub: Escolha entre Issue Tracker, Pull Requests ou um banco de dados personalizado para controlar quais dados serão sincronizados.
- Direção da sincronização e mapeamento de campos: Entenda que o Notion puxa dados do GitHub de forma unidirecional por padrão; você pode mapear propriedades do Notion para campos do GitHub.
O que a Integração Notion-GitHub Faz e o que Você Precisa
A integração Notion-GitHub cria um banco de dados vinculado que espelha issues, pull requests e outros eventos do repositório do GitHub. Quando uma nova issue é criada no GitHub, ela aparece como uma linha no seu banco de dados do Notion em minutos. Você também pode atualizar o status, os responsáveis e as labels da issue a partir do Notion se a integração estiver configurada para sincronização bidirecional. Esse recurso faz parte do sistema de Conexões do Notion e funciona com repositórios públicos e privados.
Antes de começar, você precisa de três coisas:
- Um workspace do Notion onde você tenha permissões de administrador ou proprietário. Apenas proprietários do workspace podem adicionar e configurar conexões.
- Uma conta do GitHub com acesso de administrador ao repositório que deseja sincronizar. A integração usa OAuth, então você precisa autorizar o Notion a ler e escrever nos seus repositórios.
- Um banco de dados do Notion que armazenará as issues sincronizadas. Você pode usar o modelo pré-construído Issue Tracker ou criar um banco de dados personalizado com as propriedades necessárias.
A integração suporta uma conta do GitHub por conexão do workspace. Se precisar de vários repositórios, você pode adicionar cada um como um banco de dados vinculado separado após a conexão inicial.
Passos para Conectar o GitHub e Configurar a Sincronização de Issues
Siga estes passos para configurar a sincronização entre seu workspace do Notion e o rastreador de issues de um repositório GitHub. O processo tem duas fases: conectar sua conta do GitHub e depois selecionar o repositório e o modelo de banco de dados.
- Abra as configurações do workspace do Notion
Clique em Configurações e Membros na barra lateral esquerda. Se você estiver no aplicativo web do Notion, clique no ícone do seu perfil no canto superior direito e selecione Configurações e Membros no menu suspenso. Isso abre o painel de configurações do workspace. - Navegue até a aba Conexões
No painel esquerdo da janela de configurações, clique em Conexões. Você verá uma lista de todas as integrações de terceiros atualmente vinculadas ao seu workspace. Role para baixo para encontrar a opção de integração do GitHub. - Clique em Adicionar ou Conectar GitHub
Procure o logotipo do GitHub e clique no botão Conectar. Uma nova aba ou pop-up do navegador será aberta pedindo que você autorize o Notion a acessar sua conta do GitHub. Faça login no GitHub se ainda não estiver logado. - Autorize o aplicativo OAuth do Notion no GitHub
O GitHub exibe uma lista de permissões que o aplicativo Notion solicita. Isso inclui ler e escrever issues, pull requests e metadados do repositório. Clique em Autorizar Notion para conceder acesso. Você será redirecionado de volta ao Notion. - Selecione um repositório no Notion
Após a autorização, o Notion retorna à página de Conexões. Clique no botão Configurar ao lado da integração do GitHub. Uma caixa de diálogo aparece mostrando seus repositórios do GitHub. Selecione o repositório que deseja sincronizar com o Notion. - Escolha um modelo de banco de dados
O Notion oferece três modelos: Issue Tracker, Pull Requests e Personalizado. Selecione Issue Tracker para sincronizar issues e seus metadados. Este modelo cria um novo banco de dados com propriedades pré-configuradas como Status, Responsável, Labels e Marco. - Defina a direção da sincronização
Na mesma caixa de diálogo, escolha se a sincronização será unidirecional (do GitHub para o Notion) ou bidirecional. A sincronização unidirecional significa que as alterações no GitHub aparecem no Notion, mas as alterações no Notion não são enviadas de volta ao GitHub. A sincronização bidirecional permite que você atualize o status, os responsáveis e as labels das issues a partir do Notion e essas alterações sejam refletidas no GitHub. - Clique em Conectar e aguarde a sincronização inicial
Clique no botão Conectar para finalizar a configuração. O Notion começa imediatamente a importar as issues existentes do repositório selecionado. Dependendo do número de issues, isso pode levar de alguns segundos a alguns minutos. Você verá o novo banco de dados aparecer na barra lateral do seu workspace.
Após a sincronização inicial, novas issues criadas no GitHub aparecerão automaticamente no banco de dados do Notion. Se você ativou a sincronização bidirecional, pode editar propriedades como Status ou Responsável diretamente no banco de dados do Notion e as alterações serão sincronizadas de volta ao GitHub.
Problemas Comuns ao Sincronizar Issues do GitHub com o Notion
Issues não aparecem no Notion após a conexão
Se nenhuma issue aparecer no banco de dados do Notion após a sincronização inicial, verifique se o repositório realmente contém issues. Alguns repositórios usam Discussões ou Projetos em vez da aba Issues. Confirme também se a integração do GitHub tem acesso de leitura ao repositório. Vá para GitHub > Configurações > Aplicativos > Aplicativos OAuth Autorizados e verifique se o Notion aparece na lista. Se aparecer, revogue o acesso e reconecte a partir do Notion.
Atualizações da sincronização bidirecional não são refletidas no GitHub
A sincronização bidirecional exige que os nomes das propriedades do banco de dados do Notion correspondam exatamente aos nomes dos campos do GitHub. Por exemplo, uma propriedade chamada “Status” no Notion deve corresponder ao campo de status da issue do GitHub. Se você renomear uma propriedade após a configuração da sincronização, a conexão será quebrada. Exclua o banco de dados vinculado e reconecte com o modelo correto. Não edite manualmente os nomes das propriedades no banco de dados do Notion após a configuração.
A sincronização para de funcionar após uma alteração de permissão no GitHub
Se você ou um administrador da organização do GitHub alterar as permissões do aplicativo OAuth, a sincronização pode parar. Os sintomas incluem dados desatualizados ou mensagens de erro no banco de dados. Para corrigir isso, vá para Configurações e Membros do Notion > Conexões, clique no menu de três pontos ao lado do GitHub e selecione Reconectar. Isso reautoriza a integração com as permissões atuais.
Issue Tracker do Notion vs Modelo Pull Requests vs Banco de Dados Personalizado
| Item | Issue Tracker | Pull Requests | Banco de Dados Personalizado |
|---|---|---|---|
| Dados sincronizados | Issues do GitHub com status, responsável, labels, marco, comentários | Pull requests do GitHub com status, revisor, branch, status de merge | Você define quais eventos e campos do GitHub sincronizar |
| Propriedades pré-configuradas | Status, Responsável, Labels, Marco, Repositório, Número da Issue | Status, Revisor, Branch, Status de Merge, Repositório, Número do PR | Nenhuma — você cria todas as propriedades manualmente |
| Melhor para | Rastreamento de bugs, solicitações de recursos, gerenciamento de tarefas | Fluxo de revisão de código, rastreamento de merges | Usuários avançados que precisam apenas de campos específicos ou vários repositórios em um banco de dados |
| Suporte a sincronização bidirecional | Sim — status, responsável, labels sincronizam de volta ao GitHub | Limitado — status e revisor sincronizam de volta | Depende do mapeamento de propriedades; pode exigir manutenção manual |
O modelo Issue Tracker é o ponto de partida recomendado porque inclui todos os campos comumente usados e suporta sincronização bidirecional completa. Mude para o modelo Pull Requests se seu objetivo principal for rastrear revisões de código. Use o banco de dados personalizado apenas se precisar combinar dados de vários repositórios ou sincronizar eventos que os modelos não cobrem.
Agora você tem um banco de dados do Notion funcional que sincroniza com o rastreador de issues do seu repositório GitHub. Novas issues criadas no GitHub aparecerão automaticamente, e você pode atualizar o status das issues a partir do Notion se ativou a sincronização bidirecional. Para estender essa configuração, tente adicionar uma visualização vinculada que filtre issues por responsável ou marco. Para equipes que usam vários repositórios, considere criar um banco de dados separado para cada repositório para manter os dados organizados.