> ## 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.

> [!NOTE]
>
> TextQL supports both product-native context (managed in the [Context Editor](https://docs.textql.com/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](https://docs.textql.com/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](https://docs.textql.com/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

**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](https://mintcdn.com/textql/WTo4QmI95S9LmbVe/images/guides/github-memory/context_repo.png?fit=max\&auto=format\&n=WTo4QmI95S9LmbVe\&q=85\&s=58743e94143dd2e95e272783986a5aaa)

**2. Create a personal access token**

Go to [GitHub Settings > Developer settings > Personal access tokens](https://github.com/settings/personal-access-tokens/new) and generate a new token.

![Generate GitHub personal access token](https://mintcdn.com/textql/WTo4QmI95S9LmbVe/images/guides/github-memory/access_token2.png?fit=max\&auto=format\&n=WTo4QmI95S9LmbVe\&q=85\&s=c4706b3ed7bbe0364726ecadd0acc67e)

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

![Select repository scope permissions](https://mintcdn.com/textql/WTo4QmI95S9LmbVe/images/guides/github-memory/scope.png?fit=max\&auto=format\&n=WTo4QmI95S9LmbVe\&q=85\&s=09512b90ad21eaddba41e69e1c262649)

Click **Generate token** and copy it — you won't be able to see it again.

**3. Add the token to TextQL**

Navigate to [API Connectors](https://docs.textql.com/core/datasources/api-connectors.md) in TextQL and add the token as a connector named `ana_context_access_token`.

![Add GitHub token to secrets](https://mintcdn.com/textql/WTo4QmI95S9LmbVe/images/guides/github-memory/secrets.png?fit=max\&auto=format\&n=WTo4QmI95S9LmbVe\&q=85\&s=ad1716e3e23e0a4d11964a3bff3eab25)

Then add the configuration key for the repository:

![Configure repository access key](https://mintcdn.com/textql/WTo4QmI95S9LmbVe/images/guides/github-memory/config_key.png?fit=max\&auto=format\&n=WTo4QmI95S9LmbVe\&q=85\&s=9b98446a0fb43ca923510634202dfd15)

**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.

> [accordion] Example system prompt template
>
> ```
> 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
> ```

![Configure organization context prompt](https://mintcdn.com/textql/WTo4QmI95S9LmbVe/images/guides/github-memory/organization_context.png?fit=max\&auto=format\&n=WTo4QmI95S9LmbVe\&q=85\&s=742cae83312825f1a1a5177fc4d1da6f)

## Demo: GitHub context in action

Ana references the context repository to understand previous work and team preferences:

![Ana accessing persistent memory for context](https://mintcdn.com/textql/WTo4QmI95S9LmbVe/images/guides/github-memory/usecase.png?fit=max\&auto=format\&n=WTo4QmI95S9LmbVe\&q=85\&s=debc773cad3800ec843f722326c7a174)

Ana retrieves and applies stored context, providing responses aligned with previous work and established patterns:

![Ana applying persistent memory to deliver contextual results](https://mintcdn.com/textql/WTo4QmI95S9LmbVe/images/guides/github-memory/result.png?fit=max\&auto=format\&n=WTo4QmI95S9LmbVe\&q=85\&s=2a967d05a6cd2fa28fb7ba05a6fd4365)

## Best practices

> [accordion] Always review pull requests manually
>
> 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.

> [accordion] Keep files focused
>
> 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.

> [accordion] Protect your main branch
>
> Configure GitHub branch protection to require PR reviews before merging and prevent direct commits to main.

> [accordion] Rotate tokens periodically
>
> 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

> [card] [Dynamic Context Loading](https://docs.textql.com/core/guides/context/github-dynamic-loading)
>
> How Ana navigates your repository to fetch only the files relevant to each question

> [card] [Version-Controlled Context Writing](https://docs.textql.com/core/guides/context/github-version-control)
>
> How Ana proposes context changes via pull requests and why the PR workflow matters


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.