Connect GitHub to Cortex
Connect selected organization repositories through a GitHub App installation.
GitHub
GitHubContent and access
Pull request, issue, and commit metadata from selected organization repositories. Cortex does not clone repositories or read source file contents.
Set up GitHub
An admin connects this app for the Cortex organization. Grant access only to content appropriate for the whole organization.
What you need: someone allowed to install GitHub Apps for the GitHub organization.
- In Cortex, open Organization → Apps and add GitHub.
- Continue to GitHub and install the Cortex GitHub App for the GitHub organization. Personal GitHub accounts are not supported.
- During installation, choose the repositories Cortex may access.
- Complete the GitHub authorization step and return to Cortex.
- Select Test & preview. The preview lists repositories from the installed organization.
If you cannot install GitHub Apps yourself
- Select Send GitHub owner link at the top of Apps.
- Enter the organization's URL handle, such as
acmefromgithub.com/acme. Use letters, numbers, and hyphens; display names are not accepted. - Send the generated link to a GitHub owner. It works only for that organization and expires after 72 hours. The owner does not need a Cortex account.
How access works
Cortex stores the GitHub App installation, not a GitHub user's access token. Repository access follows the repositories chosen for that installation, so widening or narrowing it is a change you make in GitHub.
Technical details
Cortex reaches GitHub only through outbound HTTPS calls: api.github.com as the Chaos Labs GitHub App chaos-labs-cortex, and github.com once for the owner authorization step. The App subscribes to no webhook events, so GitHub never calls into Cortex.
Authentication
- The connection is a GitHub App installation on your organization. Before Cortex saves it, it resolves the installation with an App JWT, then asks the installing user to authorize so it can confirm through GitHub that they are an active organization owner who can see that installation. That user authorization token is held in memory for those checks and discarded.
- Cortex stores the installation ID, the GitHub organization handle, and the verified installation identity. It never stores personal access tokens or user tokens. For the Cortex GitHub App, the private key lives in Chaos Labs secrets management, not on the connection.
- To read, Cortex signs an App JWT that expires in under ten minutes and exchanges it for an installation token that GitHub expires after about one hour. That token is cached in process memory until five minutes before expiry and is never written to storage.
- Install links are bound to a one-time state held in Redis: ten minutes for a direct install, 72 hours for an owner link. The installation ID GitHub returns in the browser is never trusted on its own.
What Cortex reads
Repository access follows the repositories selected on the installation. Within them, Cortex reads through the GitHub GraphQL API:
| Data | Fields |
|---|---|
| Repositories | Name, archived and disabled flags |
| Pull requests | Title, description (first 4,000 characters), state, labels, milestone, assignees, branch names, timestamps, author login, reviewers and review state, linked issues, project board links, changed file paths, commit SHAs, URL |
| Issues | Title, description (first 4,000 characters), state and state reason, labels, assignees, timestamps, author login, URL |
| Commits | Default-branch history: SHA, message, author login, date |
| Weekly digest only | For items in the week: the first 20 comments on each issue (author login and text), pull request commit messages, and added and deleted line counts |
Search and Ask also call GitHub live with the same installation token, limited to repository, issue, and pull request search and pull request listing.
Cortex does not clone repositories and does not read file contents, diffs or patches, pull request review comment text, Actions logs, secrets, or contributor email addresses. The permissions Cortex uses are repository Metadata, Contents, Pull requests, and Issues (read) and organization Members (read). GitHub shows the App's full permission list on the installation screen.
Where data is stored
Pull request, issue, and commit metadata is written to Cortex's Postgres database, in tables keyed by your Cortex organization ID. The installation credential is encrypted at rest with a Cortex-held key in the same database, and connection changes are written to the audit log. Ingestion runs every 15 minutes over the previous two days (the pull request lane widens to seven days after a gap), and a weekly digest covers the previous seven days; the digest sends issue titles, descriptions, and comment excerpts to a model call. Retrieval indexes for Search and Ask are built from these stored rows and kept in the same database; model calls run through Cortex's model gateway under the providers agreed for your deployment.
Revoke and delete
Revoke or Delete stops new token minting immediately and is written to the audit log; ingestion stops at its next scheduled run, and an installation token already issued expires within the hour. Neither uninstalls the App from GitHub: remove it under your GitHub organization's Settings → GitHub Apps. Metadata already captured stays under your organization's retention terms; contact Chaos Labs to purge it.
Manage this connection
After changing permissions in GitHub, return to Organization → Apps and run Test & preview. A preview is a limited sample of accessible content.
See the shared connection management guide for credential updates, reauthorization, and revocation. The complete GitHub procedure is also available in Workplace connections.