GitHub Integration
Octokraft connects to GitHub through a GitHub App. The app receives webhook events when pull requests are opened and code is pushed, and has read access to your repository contents for analysis.Installation
Connect GitHub
Click Connect GitHub. You will be redirected to GitHub to install the Octokraft GitHub App.
Choose access level
Select whether to grant access to all repositories or only selected repositories in your organization. You can change this later from your GitHub settings.
Permissions Required
The Octokraft GitHub App requests the following permissions:| Permission | Access | Purpose |
|---|---|---|
| Repository contents | Read | Analyze source code for health scoring, convention detection, and architecture review |
| Pull requests | Read & Write | Read PR metadata and diffs, post analysis results as comments |
| Metadata | Read | Repository information (name, language, default branch) |
| Webhooks | Read & Write | Receive events when PRs are opened, updated, or merged and when code is pushed |
Octokraft requests only the permissions it needs. Repository contents are accessed read-only and are never modified. Write access to pull requests is used solely to post analysis results.
What Triggers Analysis
| Event | What Happens |
|---|---|
| PR opened or updated | PR analysis runs automatically. Issues are detected, merge readiness is evaluated, and results are posted to the PR. |
| PR merged to default branch | An incremental health assessment runs. Scores are recalculated based on the changes introduced by the merge. |
| Code pushed to default branch | The code graph and detected conventions are updated to reflect the latest state of the codebase. |
Repository Selection
After installing the GitHub App, you manage which repositories are tracked from inside Octokraft:- Go to the Repos page in your project.
- Click Add Repository.
- Select repositories from the list of available repos (filtered by your GitHub App installation).
- Confirm your selection.
Troubleshooting
Pull request is not being analyzed
Pull request is not being analyzed
Verify the following:
- The repository is added to your Octokraft project (check the Repos page).
- The Octokraft GitHub App is installed on the organization that owns the repository.
- Webhooks are active. Go to your GitHub organization settings, find the Octokraft app installation, and confirm that webhooks are being delivered.
Analysis appears stuck
Analysis appears stuck
Open the PR in Octokraft and check the analysis status. If analysis has been running for more than 10 minutes, there may be an issue with the analysis worker. For self-hosted deployments, check that the worker service is running and healthy.
Missing permissions error
Missing permissions error
If Octokraft reports insufficient permissions, reinstall the GitHub App:
- Go to your GitHub organization settings.
- Find the Octokraft app under Installed GitHub Apps.
- Click Configure and verify the permissions match those listed above.
- If permissions are missing, uninstall and reinstall the app from Settings > Source Control in Octokraft.
Repository not appearing in the add list
Repository not appearing in the add list
The repository list is filtered by your GitHub App installation. If a repository does not appear:
- Confirm the app is installed on the correct organization.
- Confirm the app has access to that specific repository (if you chose “selected repositories” during installation).
- You can update repository access from your GitHub organization settings under Installed GitHub Apps > Octokraft > Configure.