Skip to main content
TextQL supports both product-native context (managed in the 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:
CapabilityWhat it means
Dynamic context loadingAna reads live files from your repo at query time — not a static snapshot baked into the context library
Version-controlled context writingAna 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 LibraryGitHub Repository
Best forUniversal rules, short definitions, quick setupLarge knowledge bases, structured documentation, team-maintained content
Loading behaviorEntire document loaded on every conversationRelevant files fetched dynamically per question
EditingTextQL UIAny text editor, Git workflow
Version historyNoneFull Git history
CollaborationTextQL users onlyAnyone with GitHub access
Ana can write to itYes (with permission)Yes, via pull requests
Setup requiredNoneGitHub 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

1

Create a GitHub repository

Create a new repository on GitHub (can be private). Name it something like ana-context or textql-context.Create GitHub repository for Ana's context
2

Create a personal access token

Go to GitHub Settings > Developer settings > Personal access tokens and generate a new token.Generate GitHub personal access tokenConfigure 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
Select repository scope permissionsClick Generate token and copy it — you won’t be able to see it again.
3

Add the token to TextQL

Navigate to your TextQL settings > Configuration > Secrets Enabled > Manage Secrets and add the token as a secret named ANA_CONTEXT_ACCESS_TOKEN.Add GitHub token to secretsThen add the configuration key for the repository:Configure repository access key
4

Configure the system prompt

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 = SECRETS['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
Configure organization context prompt

Demo: GitHub context in action

Ana references the context repository to understand previous work and team preferences: Ana accessing persistent memory for context Ana retrieves and applies stored context, providing responses aligned with previous work and established patterns: Ana applying persistent memory to deliver contextual results

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

Dynamic Context Loading

How Ana navigates your repository to fetch only the files relevant to each question

Version-Controlled Context Writing

How Ana proposes context changes via pull requests and why the PR workflow matters