GitHub App

CommitMind uses a GitHub App to fetch commit history and metadata for the repositories you connect. This page explains what installing grants, how to pick repositories, and how to revoke access.

You only need the App for team mode — repos shared across teammates, where commits should be ingested via webhooks instead of from a single developer's local clone. Solo workflows can capture commits from commitmind running locally without installing anything on GitHub. See the Quickstart for the difference.

What installing grants

The App is configured to request the smallest set of read-only scopes that lets us index a repository's commit history. We never request write access of any kind.

• Repository metadata (read) — names, descriptions, default branches, visibility. Used by the dashboard's repo picker so you can browse what the App can see.
• Repository contents (read) — commit history, individual commit metadata, and (on demand, for the symbol index) file contents at a specific commit SHA. We do not store full file contents in our database — we read blobs to build the symbol index, then drop them.
• Pull requests (read) — surfaces PR titles and review-state in the dashboard timeline alongside the underlying commits.

The App subscribes to push webhook events. New commits land in CommitMind within seconds of git push, with no need to git fetch from a developer machine.

GitHub shows the exact permissions on the install screen before you confirm — what you see there is authoritative.

Install

You install from the dashboard rather than directly from GitHub so we can scope the install to the right CommitMind organization:

1. Open the dashboard and select the org you want to connect.
2. Go to Organization settings → GitHub (or click Connect GitHub on a project's empty state).
3. Click Connect GitHub. We redirect you to GitHub's official install screen for the CommitMind App.
4. Pick the GitHub account or organization to install on. If you manage multiple GitHub orgs, GitHub will list them; pick the one that owns the repos you want to ingest.
5. Pick which repositories the App can see. Only selected repositories is the safer default — install on the repos you want indexed, leave the rest untouched. All repositories is a convenience for orgs that want every repo indexed.
6. Confirm. GitHub redirects you back to the dashboard, and the GitHub App is now wired to your CommitMind org.

If your CommitMind org isn't a personal workspace, only org admins can install the App. CommitMind's API rejects the install request from non-admin members with a 403.

Pick or change which repositories

The set of repos the App can see is managed entirely on GitHub — we don't store a list on our side. To add or remove repositories after the initial install:

1. Go to github.com → Your settings (or org settings) → Applications → Installed GitHub Apps → CommitMind → Configure.
2. Under Repository access, add or remove repos. Switching between "All repositories" and "Selected repositories" is also done here.
3. Save. Changes apply within a few seconds — the dashboard's repo picker re-reads the list on each open.

You don't need to reinstall after changing repo selection.

Personal account vs organization installs

The App can be installed on either a personal GitHub account or an org — which one to pick depends on where the repos you want to ingest live:

• Personal account install — covers personal repositories owned by your GitHub username. Right choice for solo or hobby work where the repos aren't owned by a GitHub organization.
• Organization install — covers repositories owned by that GitHub org. Right choice for team repos. Only GitHub-org owners or members with the Manage installed apps permission can install on an org.

You can install on both your personal account and an organization independently — they're separate installations from CommitMind's point of view. The dashboard groups the resulting repos by their GitHub owner so the picker stays scannable.

Revoke access

Two ways to remove the App:

• From GitHub — github.com → settings → Applications → Installed GitHub Apps → CommitMind → Uninstall. Immediate; revokes the installation token, stops webhook delivery, and our APIs that rely on installation auth start returning a "not connected" state.
• From the dashboard — the GitHub settings page surfaces a disconnect action that calls GitHub's uninstall API on your behalf. Equivalent outcome.

Uninstalling does NOT delete commit data we've already ingested. If you also want CommitMind to forget the commits we previously indexed, delete the project (or the org) from the dashboard — that cascades to all the commit / decision / observation rows tied to it.

Troubleshooting

The dashboard's repo picker is empty after installing. The most common cause is that you installed on a different GitHub account than the one that owns your repos. Visit github.com → Applications → Installed GitHub Apps to see where the App is installed, and either pick new repos there or install on the right account/org.

"Connect GitHub" doesn't show me my org as an option on the install screen. GitHub only lists orgs where you have Manage installed apps permission. Ask a GitHub-org owner to either install on your behalf or grant you the permission, then retry.

I see a 404 from /orgs/<slug>/github/repos in the dashboard. That endpoint returns 404 with code no_github_installation when the CommitMind org has never installed the App. The dashboard maps the 404 to a "Connect GitHub" prompt — clicking through completes the install and the picker repopulates on the next render.

A repo I expected to see isn't in the picker. Either the repo isn't in the App's selected-repository list (check the App configuration on GitHub) or the repo is owned by a different account than the one that holds the installation. Adding it on GitHub takes effect immediately.

Next steps

• Quickstart — the full installation flow including the local CLI and editor wiring.
• Automatic decisions — what CommitMind surfaces from the commits it ingests.