Connect GitHub
Unyform reads your code through a GitHub App you install on the account or organization that owns your repositories. Once connected, Unyform can clone the repos you select, build their code knowledge graph, and produce blueprints that govern your AI tools.
This guide walks you from zero to a connected repo ready to analyze.
1. Open the Connections page
In the dashboard, go to Settings → Connections. The GitHub App card at the top is labeled Connect GitHub App and marked Recommended.
Note
The GitHub App is the recommended path — it sets up webhooks and PR checks automatically. The Personal Access Token option below it is a fallback for accounts where you can't install an App.
2. Install the GitHub App
Click Install GitHub App. GitHub opens the App's installation page in the same tab.
On GitHub:
- Choose the account or organization that owns the repositories you want to govern.
- Under Repository access, pick either All repositories or Only select repositories, then choose the repos you want Unyform to see.
- Click Install (or Save if you're updating an existing installation).
Tip
Start with Only select repositories and add the one or two repos you want to try first. You can widen access later from GitHub → Settings → Applications.
The App requests read-only access to the repositories you select — it reads code contents and the file tree to build your knowledge graph and blueprints. It never writes to your code.
3. Let the callback finish
GitHub redirects you back to Unyform. You'll see a Setting up GitHub App... screen while the installation is registered, then GitHub App Connected! before you're taken back to the dashboard.
The Connections page now shows the GitHub App card in the connected state, displaying the account it's installed on.
Note
Unyform also registers a webhook during install. From then on, GitHub notifies Unyform of pushes to your connected repos. Webhook deliveries are HMAC-verified, so only genuine GitHub events are accepted.
4. Pick a repository and analyze
Go to Repositories and open the New Analysis tab.
- Confirm the GitHub Connection dropdown shows the account you just connected.
- Search the repository list and click the repo you want to analyze.
- In Analysis Configuration, set the Branch (defaults to the repo's default branch).
- Under Blueprint, leave Create new blueprint selected for a first run, or pick an existing blueprint to add a new version.
- Click Start Analysis.
Unyform clones the repo, builds the knowledge graph, mines idioms, and writes a blueprint plus code embeddings. You'll land on the Active tab, where the job shows live progress. When it finishes, it moves to History.
Tip
Next: attach the blueprint to a gateway and point your AI tool at it — see the Quickstart.
Disconnect
To remove the integration, return to Settings → Connections and click Disconnect on the GitHub App card. This deactivates the installation in Unyform. To fully uninstall the App from GitHub's side, also remove it from GitHub → Settings → Applications → Installed GitHub Apps.
Troubleshooting
The callback didn't return / I got an "Invalid installation ID" error. Make sure you completed the install on GitHub (clicked Install or Save) rather than closing the tab. Retry from Settings → Connections → Install GitHub App.
A repository I expected isn't in the New Analysis list. The App can only see repos included in its installation scope. On GitHub, go to Settings → Applications → Installed GitHub Apps → Unyform → Configure, and under Repository access add the missing repo (or switch to All repositories). The repo appears in Unyform once the scope is updated.
The connection card shows "Connect GitHub App" again after I installed it. This usually means a stale installation. Reinstall from the card; Unyform keys on the most recent active installation for your org.
Warning
Repository access is org-scoped. Anyone who installs or reconfigures the App is changing what your whole organization can govern — coordinate with your team before widening or removing access.