> ## Documentation Index
> Fetch the complete documentation index at: https://docs.textql.com/llms.txt
> Use this file to discover all available pages before exploring further.
# GitHub Integration for Context
> Connect Ana to a GitHub repository to load context dynamically and version-control context updates through pull requests.
TextQL supports both product-native context (managed in the [Context Editor](/core/guides/context/context-editor)) and GitHub-based context. They complement each other and can be used together.
The GitHub integration is often described as "version control for context." That is true, but it undersells the more important capability: **Ana reads from the repository at the start of each conversation, dynamically loading only the files relevant to the question being asked.**
These are two distinct features that happen to use the same GitHub connection:
| Capability | What it means |
| ------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
| **[Dynamic context loading](/core/guides/context/github-dynamic-loading)** | Ana reads live files from your repo at query time — not a static snapshot baked into the context library |
| **[Version-controlled context writing](/core/guides/context/github-version-control)** | Ana proposes context changes via pull requests; humans review and approve before anything merges |
Most teams get more immediate value from dynamic loading. Version control becomes important as your context matures and multiple people are maintaining it.
## Product-native context vs. GitHub context
| | Product-Native Context Library | GitHub Repository |
| ----------------------- | ----------------------------------------------- | ------------------------------------------------------------------------ |
| **Best for** | Universal rules, short definitions, quick setup | Large knowledge bases, structured documentation, team-maintained content |
| **Loading behavior** | Entire document loaded on every conversation | Relevant files fetched dynamically per question |
| **Editing** | TextQL UI | Any text editor, Git workflow |
| **Version history** | None | Full Git history |
| **Collaboration** | TextQL users only | Anyone with GitHub access |
| **Ana can write to it** | Yes (with permission) | Yes, via pull requests |
| **Setup required** | None | GitHub repo + personal access token |
**A common pattern:** Put your universal business rules (fiscal calendar, currency conventions, key exclusions) in the product-native context library. Put your data source documentation, metric definitions, and API docs in GitHub. Ana reads both.
## Setting up the integration
Create a new repository on GitHub (can be private). Name it something like `ana-context` or `textql-context`.
Go to [GitHub Settings > Developer settings > Personal access tokens](https://github.com/settings/personal-access-tokens/new) and generate a new token.
Configure the token:
* **Repository access**: Select "Only select repositories" and choose the repository you just created
* **Expiration**: Choose an appropriate duration (e.g., 30 days)
* **Permissions**: Grant `Contents: Read and Write` so Ana can read context and write new context
Click **Generate token** and copy it — you won't be able to see it again.
Navigate to [API Connectors](/core/datasources/api-connectors) in TextQL and add the token as a connector named `ana_context_access_token`.
Then add the configuration key for the repository:
Add a system prompt that tells Ana the repository exists, how to access it, and how to navigate it. This is where you specify whether Ana should read a navigation index first, what kinds of questions should trigger a context lookup, and whether she should write context changes back via PRs.
```
BEFORE doing ANYTHING - ESPECIALLY AT THE START OF A NEW CHAT:
1. Read overview.md from GitHub using ana_context_access_token
2. NEVER make assumptions about how APIs work
3. ALWAYS read supporting documentation from the context repo before using any API
4. Use provided Python code - DO NOT use web search for API documentation
GitHub Access Code:
import requests
import base64
GITHUB_PAT = ana_context_access_token
headers = {
'Authorization': f'token {GITHUB_PAT}',
'Accept': 'application/vnd.github.v3+json'
}
# REPLACE WITH YOUR VALUES
REPO_OWNER = "your-github-username"
REPO_NAME = "your-repo-name"
# Reading files from the context repo:
url = f"https://api.github.com/repos/{REPO_OWNER}/{REPO_NAME}/contents/overview.md"
response = requests.get(url, headers=headers)
content = base64.b64decode(response.json()['content']).decode('utf-8')
Role:
Ana helps keep context updated via GitHub access token. She maintains persistent memory across sessions by reading and writing to the context repository.
When to Save:
Save when user says:
- "remember", "save", "store", "keep in mind"
- Provides preferences or instructions
- Likes a graph, visualization, or code cell
- Shares important information for future sessions
Save Procedure:
1. Create a new branch (never push to main)
2. Write to appropriate location (e.g., apis/{service-name}/ for API docs)
3. Create descriptive PR
4. Confirm to user
```
## Demo: GitHub context in action
Ana references the context repository to understand previous work and team preferences:
Ana retrieves and applies stored context, providing responses aligned with previous work and established patterns:
## Best practices
Never auto-merge PRs from Ana. Always manually review to ensure changes are accurate, don't contain sensitive information, and will produce the desired behavior.
Create multiple focused files rather than one large file. This makes PR reviews easier, version history clearer, and dynamic loading more precise — Ana fetches whole files, so smaller files mean more targeted context.
Configure GitHub branch protection to require PR reviews before merging and prevent direct commits to main.
Rotate your GitHub personal access token regularly and use an appropriate expiration window. Update the secret in TextQL when you rotate.
## Troubleshooting
**Ana can't access the repository**
* Verify the PAT has correct permissions (`Contents: Read and Write`)
* Check the repository URL and owner are correct in the system prompt
* Ensure the repository is not empty
* Confirm the PAT hasn't expired
**Context not updating after a merge**
* Verify changes are merged to the main branch
* Check that files are in markdown format (`.md`)
* Start a new chat to trigger a fresh context read
**Pull requests not being created**
* Verify the PAT has write permissions to branches
* Check that repository settings allow PR creation
* Ensure the system prompt includes instructions for Ana to save context
How Ana navigates your repository to fetch only the files relevant to each question
How Ana proposes context changes via pull requests and why the PR workflow matters