Skip to main content

​
1. Overview

The GitHub connector gives Ana direct access to your organization’s repositories, pull requests, issues, and code activity via the GitHub REST and GraphQL APIs. Once configured, Ana can answer engineering questions in natural language, surface trends across your codebase, and join GitHub data with your connected data warehouse for cross-source analysis. Note that Ana operates in read-only mode by default — it can propose context changes via pull requests, but cannot trigger GitHub Actions or push code directly.
Connect your GitHub organization to Ana via GitHub App or OAuth 2.0 to enable natural language querying of repos, PRs, and issues alongside your warehouse data.

​
2. Prerequisites

You’ll need:
  • A GitHub account with access to the repositories you want Ana to query
  • Owner or admin access to your GitHub organization if you are setting up an org-level integration via GitHub App
  • A TextQL account with permission to add API connectors

​
Which type of connection should I use?

Personal Access Token (PAT)OAuth (Org-level)OAuth (Per-member)
Best forIndividual use, scripts, or quick setupTeam or company-wide GitHub access under org policiesMulti-user SaaS where each user connects their own GitHub
ScopeSingle user’s GitHub permissionsOrganization-controlled access + user permissionsIndividual user’s GitHub permissions
AuthenticationFine-grained or classic PAT (manual token)OAuth 2.0 user authentication (may require org approval)OAuth 2.0 per user consent
Access modelFixed to one GitHub accountControlled by org policy, still per-user tokensFully user-isolated tokens
Admin involvementNoneSometimes required (org approval)None (unless org restricts apps)

​
3. Capabilities

Once configured, Ana can:
  • Fetch and search repositories, branches, files, and commit history
  • Query open and closed pull requests, filter by author, status, label, date, or reviewer
  • Surface code review patterns, such as PR cycle times, review bottlenecks, and merge rates
  • Join GitHub activity data with your data warehouse for cross-source analysis, like correlating deploy frequency with business metrics
  • Load live files from your repo dynamically as context for each conversation
  • Answer engineering questions in natural language, like “Which PRs have been open the longest?” or “How many issues were closed last month by team?”
The integration uses GitHub App or OAuth 2.0 with read-only access to your GitHub data.

​
4. Setup Instructions

​
Step 1: Generate your GitHub credentials

  1. Go to github.com and sign in.
  2. Navigate to settings by clicking on your profile icon in the top right corner.
  3. On the left sidebar of your settings, scroll to the bottom and click Developer Settings.
  4. Click Personal Access Tokens. There are two types of Personal Access Tokens that GitHub offers:
    • Fine-grained tokens (recommended): Scoped to specific repositories you select — Ana will only be able to access those repositories and nothing else. Use this if you want to limit Ana to one or a few repos. Each permission can be set to No access, Read-only, or Read and write. For Ana, we recommend enabling Read-only access for: Contents, Issues, Pull Requests, and Metadata.
    • Tokens (classic): Grant Ana access to all repositories available to your GitHub user or organization — Ana is not limited to specific repos. Use only if fine-grained tokens are not supported for your workflow.
Which token type should I use? Use a fine-grained token if you want Ana to connect only to specific repositories. Use a classic token if you want Ana to have access to all repositories available to the user or organization.
  1. Click Generate new token.
  2. Enter a name (e.g. TextQL or Ana Integration) and set an expiration date.
    • Choose your resource owner. Select your personal GitHub account or an organization you belong to. This defines the scope boundary of the token — only repositories and resources owned by the selected account or organization will be accessible.
  3. Choose your repository access.
  4. Under permissions, grant the minimum necessary access. For more information on permissions, visit GitHub’s official API documentation.
    • Permissions will not appear until repository access (All or Selected repositories) is chosen.
    • Once repository access is set, GitHub will display available permissions. For TextQL, we recommend enabling read-only access where applicable: Contents, Issues, Pull Requests, and Metadata.
Recommended read-only permissions for the GitHub fine-grained token
  1. Click Generate token and copy the value immediately.
PATs expire on the date you set. 90 days is a reasonable default. Store the expiry date somewhere you will remember so you can rotate it before it lapses.

​
Step 2: Add GitHub as an API connector in TextQL

GitHub connector in the API Connectors panel
  1. Go to app.textql.com and sign in.
  2. In the bottom left sidebar, click Connectors > APIs and select GitHub.
  3. In the configuration panel, fill in the fields depending on your connection type:
    • Personal Access Token (PAT)
      • Name (e.g. GitHub Personal Access)
      • Authentication type: select API Token
      • Token: paste the PAT copied from Step 1
    • OAuth (Org-level or Per-member)
      • Name (e.g. GitHub OAuth)
      • Authentication type: select OAuth (org-level) or OAuth (per-member)
      • Client ID and Client Secret: paste the values copied from Step 1
      • OAuth Authentication: click Authenticate — a popup will appear asking for permissions to access your GitHub account. Click Allow.
  4. Click Save.

​
Step 3: Verify the connection

Once saved, confirm the connector is active:
  1. Go to app.textql.com.
  2. In the bottom left sidebar, click Connectors > APIs and check that GitHub appears in your list of active connectors.
  3. Open a new Ana chat and ask a simple query, such as: “List my most recently updated GitHub repositories.”
    • If Ana returns results, the connection is working. If you see an error, refer to Section 5: Troubleshooting.
If Ana returns no results rather than an error, your token may not have access to the repositories you expect. Double-check the repository access scope and permissions set in Step 1.

​
5. Usage Examples

Once configured, you can ask Ana:
  • “How many issues were closed last month, broken down by repository?”
  • “Who are the most active contributors to this repo over the past 90 days?”
  • “Summarize the open bugs labeled critical across all our repositories.”
  • “What is the average PR cycle time for the engineering team this quarter?”
  • “Show me all PRs that were merged without a review in the last 30 days.”
  • “Which repositories have had no commits in the past 6 months?”
  • “Join our GitHub deploy frequency with revenue data from the warehouse — is there a correlation between release cadence and weekly revenue?“

​
6. Troubleshooting

SymptomLikely CauseFix
401 Bad Credentials Error (Personal Access Token)Token hasn’t been configured or expiredConfirm the token was pasted correctly in Connectors → APIs → GitHub with no extra spaces. If the token has expired, generate a new one in GitHub → Settings → Developer Settings → Personal access tokens and update the connector in TextQL.
Authentication failed (OAuth org-level or per-member)Incorrect redirect URLIn your GitHub integration settings, make sure https://app.textql.com/auth/api-oauth/callback is listed exactly as a redirect URL.
Ana returns no results for repos (no error message)Personal account selected as resource owner instead of orgGo to GitHub → Settings → Developer Settings → Personal Access Tokens, regenerate the token and select your organization as the resource owner, then update the connector in TextQL.

​
7. Security Notes

  • Personal Access Tokens expire on the date set at creation. Rotate them before expiry in GitHub > Settings > Developer Settings > Personal access tokens. OAuth tokens do not have a fixed expiration date but can be revoked or invalidated at any time by the user or organization.
  • The integration is read-only by default. Ana cannot push code, modify repositories, merge pull requests, or trigger GitHub Actions. It may open pull requests as suggestions for context or workflow updates, which require human review before merging.
  • The integration uses GitHub App or OAuth 2.0 — tokens are injected at the network boundary and never stored directly by Ana. Ana cannot modify your GitHub repositories, branches, or settings.
  • To revoke access, go to GitHub > Settings > Developer Settings and delete the relevant Personal Access Token or OAuth App. In TextQL, remove the connector under Connectors > APIs > GitHub.
  • For more details on how GitHub handles API authentication and permissions, refer to GitHub’s official API documentation.

​
Need Help?

For further assistance, please contact support@textql.com.

​
Privacy Policy

For information about how we handle your data and protect your privacy, please review our Privacy Policy.