Skip to main content

Connect GitHub as knowledge source Private Preview

TL;DR

Connect GitHub to Atlan so agents can read repository READMEs, docs, and markdown files as context.

Connect

You can connect GitHub so that Atlan agents read the documentation your engineers keep next to their code: READMEs, docs folders, and markdown files.

Prerequisites​

Before you begin, make sure you have:

  • Permission to create integrations in Atlan. If you can't see Settings → Integrations, ask a workspace admin or raise a support request
  • Access to create a fine-grained personal access token in your GitHub organization
  • The list of repositories Atlan needs to read

What agents can do with this source​

  • Skim a repository to find what's worth reading
  • Read READMEs, docs, and markdown for context
  • Pull structured records out of files in the repository

Access is read-only. Agents never write to GitHub.

Create a token​

Create a fine-grained personal access token in GitHub with Contents: Read on the repositories you want Atlan to see. No other permission is required.

info

The token's repository access is the boundary for every agent that uses this connection. Scoping the token to the repositories you want in play is how you control what agents can read.

Connect it in Atlan​

  1. In your Atlan workspace, click Settings from the left sidebar.
  2. Under Team, click Integrations.
  3. Click the MCP filter, find GitHub, and click Connect.
  4. Paste your token into GitHub API token.
  5. Click Connect.

Atlan verifies the token before storing it. Once connected, the card shows when the credentials were last updated, and GitHub becomes selectable on every agent in the workspace.

Point agent at specific repositories​

The connection decides what an agent can read. Which repositories a given agent actually reads is set on the agent, under Where do you want it to look?.

Enter one repository URL per line, for example:

https://github.com/acme/api-specs
https://github.com/acme/analytics-dbt
info

This is a hint, not a filter. Leaving it empty lets the agent search everything the token can see. If a repository must never be read, exclude it from the token's scope.

Validate results​

After connecting, confirm the source works before you rely on it:

  • The GitHub card in Settings shows Connected, along with when the credentials were last updated.
  • GitHub appears as a selectable source when you create or edit an agent.
  • Run a sample run on an agent that uses GitHub. A sample publishes nothing and returns proposed items with citations, so a sample that comes back with cited results confirms the agent can read your repositories.

If a sample run returns nothing, the token most likely can't see the repositories in the agent's scope. See Troubleshooting.

Troubleshooting​

What you seeCauseFix
Connection is rejectedToken is expired, revoked, or lacks Contents: ReadCreate a new fine-grained token with Contents: Read
Agent runs complete with no outputThe token can't see the repositories named in the agent's scopeCheck the token's repository access, then re-run
A run finishes unusually fast with nothing foundThe connection was failing when the agent was createdReconnect the source, then create the agent again

Need help​

If you need assistance after reviewing this page, contact Atlan support.

See also​