Skip to main content
Community Hub
TL;DR

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

Your AI can read this via Docs MCPcurl -fsSL "https://docs.atlan.com/install-docs-mcp" | bashConnect

Connect GitHub as knowledge source Private Preview

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 personal access token in GitHub. A fine-grained token is recommended. If the repositories belong to an organization, the organization may need to approve it
  • 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​

Atlan accepts both fine-grained and classic personal access tokens. Use a fine-grained token unless you have a reason not to: it can be limited to specific repositories and to read-only access.

  1. In GitHub, go to Settings → Developer settings → Personal access tokens → Fine-grained tokens, and click Generate new token.
  2. Under Resource owner, choose the user or organization that owns the repositories.
  3. Under Repository access, select Only select repositories and pick the repositories Atlan needs to read.
  4. Under Repository permissions, set Contents to Read-only. GitHub adds Metadata: Read-only automatically. No other permission is required.
  5. Generate the token and copy it.

If the resource owner is an organization, the organization's policy may require an owner to approve fine-grained tokens. Until it's approved, the token can't read the organization's repositories. Ask an organization owner to approve it under the organization's Settings → Personal access tokens → Pending requests.

Classic token​

A classic token with the repo scope also works. A classic token can't be limited to specific repositories: it can read and write every repository your GitHub account can access. Use it only if your organization doesn't permit fine-grained tokens.

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 checks that GitHub accepts the token before storing it. This check confirms the token is valid, not that it can read your repositories, so a fine-grained token scoped to the wrong repositories, or still waiting for organization approval, still connects. Confirm repository access with a sample run, as described in Validate results. 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 does it 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 or revokedCreate a new token, then reconnect
Card shows Connected, but agent runs complete with no outputThe token can't see the repositories named in the agent's scope. For a fine-grained token, the repositories may not be selected, Contents may not be Read-only, or the organization hasn't approved the token yetCheck the token's repository access and permissions, and its approval status in the organization. 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​