Skip to main content

​
Quickstart

This guide walks you through connecting your first repository and getting your initial code health assessment. The entire process takes less than 5 minutes.

​
Setup

1

Create your account

Go to app.octokraft.com/signup and create an account using your email, Google, or GitHub credentials.
2

Create a project

A project is your workspace — it groups repositories, team members, and settings together. Give your project a name and optionally invite team members.
3

Connect GitHub

Click Connect GitHub to install the Octokraft GitHub App on your GitHub account or organization. You will be redirected to GitHub to authorize the installation. Choose which repositories Octokraft can access — you can grant access to all repositories or select specific ones.
4

Select repositories

Back in Octokraft, select the repositories you want to add to your project. Once you confirm your selection, Octokraft begins onboarding automatically.

​
Your First Analysis

After you select your repositories, Octokraft runs a full onboarding pipeline automatically. There is nothing to configure — it works out of the box. Here is what happens during onboarding:
  1. Clone and index. Octokraft clones your repositories and builds a code graph of symbols, dependencies, and relationships.
  2. Detect analyzers. Based on your tech stack (languages, frameworks, tooling), Octokraft selects the appropriate static analyzers for your codebase.
  3. Run initial analysis. Static analyzers and AI-powered analysis run against your code to identify issues across security, runtime risks, test quality, code smells, duplication, dead code, consistency, and compliance.
  4. Detect conventions. Octokraft identifies the coding conventions and architectural patterns your team already follows.
  5. Sync pull requests. Open PRs are synced and queued for analysis.
  6. Compute health assessment. All results are aggregated into your first code health score.
You can follow the progress in real time directly in the app. Each step updates as it completes.
Onboarding time depends on repository size. Most repositories complete in 1-3 minutes. Large monorepos may take longer.

​
Exploring the Dashboard

Once onboarding completes, your project dashboard is ready. Here is what you will find:

​
Code Health Dashboard

The health dashboard is the central view of your codebase quality.
  • Overall score. A number from 0 to 100 with a letter grade (A+ through F). This is your single measure of code health.
  • Category breakdown. Eight categories, each weighted by impact: Security, Runtime Risks, Test Coverage, Code Smells, Duplication, Dead Code, Consistency, and Compliance. Each category shows its own score and issue count.
  • Drift alerts. Notifications when your health score changes significantly — up or down. Drift alerts help you catch regressions early.
  • Test quality metrics. Coverage data and test health indicators, surfaced alongside the rest of your code health.

​
Architecture

The architecture view gives you a structural perspective on your codebase.
  • Dimension scores. Four dimensions rated independently: Modularity, Coupling, Scalability, and Patterns.
  • Detected conventions. The coding patterns and conventions Octokraft identified in your codebase, with conformance tracking.
  • Living documentation. Auto-generated documentation that stays in sync with your code.
  • Decision records. Architecture Decision Records (ADRs) with full lifecycle tracking.

​
Pull Requests

The PR view shows all synced pull requests with analysis details.
  • Analysis status. Whether analysis is pending, in progress, or complete.
  • Merge readiness. Each PR is classified as blocked, needs review, or ready based on the issues found.
  • Health impact. How each PR would affect your overall code health score if merged.

​
Troubleshooting

Onboarding involves multiple steps that run sequentially. If progress appears stalled, wait a few minutes — large repositories take longer to analyze. If no progress is made after 10 minutes, try removing and re-adding the repository.
Make sure the Octokraft GitHub App has access to the repository. Go to your GitHub settings, find the Octokraft app installation, and verify the repository is included in the access list.
The health score is computed as the final step of onboarding. If all other steps show as complete but no score appears, check the project dashboard — the score may take a moment to render after computation finishes.
If the GitHub authorization flow fails, make sure you have permission to install apps on the target organization. Organization owners or users with app installation permissions can complete this step.

​
Next Steps

Code Health

Understand how health scoring works, what the 8 categories measure, and how to use drift alerts.

PR Analysis

Learn how Octokraft classifies and analyzes pull requests.

Architecture Review

Explore architecture dimension scoring, convention detection, and living documentation.

MCP Integration

Connect Octokraft to your AI coding tools for context-aware development.