GitHub Integration

Navieo connects directly to your GitHub repository to scan your codebase, discover routes, and extract interactive elements — all from the dashboard. No local tooling required.

Connecting Your Repository

Go to your Navieo dashboard and open your app
Navigate to Codebase → Connect
Click Connect Repository
You'll be redirected to GitHub to install the Navieo GitHub App
Authorize Navieo for your organization (or personal account)
Select the repository that contains your application code
Click Install & Authorize

Once connected, your repository name appears in the dashboard with a green "Connected" badge.

Permissions

Review the permissions shown by GitHub during installation. The operations require:

Permission	Scope	Why
Repository contents	Read for scanning; write for outbound sync	To read source and write generated `.navieo/` artifacts on sync branches or in direct mode
Pull requests	Read & Write	To open PRs with scan results (`.navieo/sitemap.json`)
Metadata	Read-only	Required by GitHub for all Apps

Scanning does not modify product source. Outbound synchronization writes inside .navieo/; PR mode lets you review and merge those changes. Optional direct mode commits them to the configured default branch, so do not enable it if every documentation/artifact change must go through review.

Scanning Your Codebase

After connecting, go to Codebase → Scan and click Scan Codebase. Navieo will:

Detect your framework — Next.js App Router, Pages Router, or Vite
Discover supported routes — reads the framework's statically analyzable route structure via the GitHub API
Extract interactive elements — finds buttons, links, inputs, and forms in each route using AST analysis
Map selectors — generates CSS selectors using standard id, aria-label, links, roles, and semantic attributes
Build the knowledge base — stores the discovered route and element evidence for context and planning

Duration and coverage depend on repository size, framework support and provider latency. Dynamic or ambiguous code can remain unresolved; a scan is not proof that every live control was indexed.

Enrich with AI

After scanning, click Enrich with AI to generate semantic descriptions for your routes and elements. This optional step:

Adds human-readable descriptions to each route (e.g., "User settings page with profile and notification preferences")
Describes what each interactive element does (e.g., "Opens the team invitation dialog")
Adds proposed business context for review, not proof of side effects or task completion
Improves retrieval descriptions without granting executable navigation authority

The current enrichment job fetches source excerpts as well as scanner metadata and sends them to the configured AI provider. Enable it only when that sharing is appropriate. Metadata-only enrichment is not a generally shipped option. Timing varies; failed enrichment leaves static evidence available. It is not required for live-first guidance.

Re-Scanning

Click Scan Codebase again at any time to refresh your knowledge base after code changes. Each scan is a full replacement — new routes appear and deleted routes are removed.

After a scan, Navieo opens a Pull Request on your repository with the updated .navieo/sitemap.json file. You can review and merge this PR to keep your repo in sync with the scan results.

Sync to GitHub

Click Sync to GitHub on the Scan page to request synchronization of the current generated artifacts using the configured PR/direct mode. This is not an instruction to force-push or rewrite repository history.

Supported Frameworks

Framework	Detection	Route Scanning
Next.js App Router	`app/` directory detected	`app/**/page.tsx` files
Next.js Pages Router	`pages/` directory detected	`pages/*/.tsx` files
Vite / React SPA	`vite.config.*` detected	Generic component scanning

Configuration

You can customize scanning behavior by adding a .navieo/config.json file to your repository:

{
  "framework": "nextjs",
  "srcDir": "src",
  "ignore": ["src/admin/**", "src/internal/**"]
}

Field	Description	Default
`framework`	`"nextjs"`, `"nextjs-pages"`, `"vite"`, or `"unknown"`	Auto-detected from file structure
`srcDir`	Source directory relative to repo root	`"src"` if it exists, otherwise `""`
`ignore`	Glob patterns to exclude from scanning	Test files, `__tests__`, `node_modules`

If this file doesn't exist, Navieo uses sensible defaults.

Dashboard → GitHub Sync

When you edit docs in the Navieo dashboard, changes are automatically synced back to your repository:

Docs saved in the dashboard create or update .navieo/docs/{slug}.md files via PR
Scan results are written to .navieo/sitemap.json via PR

You can configure the sync mode in your GitHub settings:

Mode	Behavior
PR (default)	Changes open a Pull Request for review
Direct	Changes commit directly to the default branch

Subsequent saves push new commits to the same open PR instead of creating new ones (no PR spam).

Disconnecting

To disconnect your repository:

Go to Codebase → Connect in your dashboard
Click Disconnect

This removes the GitHub connection but does not delete your existing scan data. Tours continue to work with the last scan results. You can reconnect the same or a different repository at any time.

Webhook Events

When your repo is connected, Navieo automatically processes these GitHub events:

Event	What Navieo Does
Push to `.navieo/sitemap.json`	Reconciles the scanned sitemap and embeddings
Push to `.navieo/docs/*.md`	Syncs doc pages to the dashboard
App installation/uninstallation	Updates connection status

Product Code Boundary

Navieo scans product code read-only and never inserts selectors, auth wiring, reveal controls or targeting attributes. Selector extraction uses ordinary application evidence. The supported data-navieo-navigation-intent="exclude" annotation is an owner safety denial, not a targeting hook; it must not be used to fabricate evidence. See owner exclusions.

Live guidance can use an eligible visible link even when the scanner missed that individual link, provided its destination is indexed and policy permits it. Opening hidden controls still needs scanner support. Keep your scan current and report unsupported patterns. See release compatibility for SDK support.