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 Integrations → GitHub
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

The Navieo GitHub App requests minimal permissions:

Permission	Scope	Why
Repository contents	Read-only	To read your source code files for scanning
Pull requests	Read & Write	To open PRs with scan results (`.navieo/sitemap.json`)
Metadata	Read-only	Required by GitHub for all Apps

Navieo never modifies your source code. The only files it writes are inside the .navieo/ directory via Pull Requests that you review and merge.

Scanning Your Codebase

After connecting, go to the Scan page in your dashboard and click Scan Codebase. Navieo will:

Detect your framework — Next.js App Router, Pages Router, or Vite
Discover all routes — reads your app/ or pages/ directory 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 id, aria-label, data-navieo-id, and semantic attributes
Build the knowledge base — stores the complete route and element map for the AI

The scan typically takes 5–30 seconds depending on repository size.

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")
Maps business context (e.g., "Billing is the revenue center. Plan upgrades take effect immediately.")
Improves tour quality by giving the AI richer understanding of your application

Enrichment runs once per scan and takes 10–45 seconds depending on route count.

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 force-push the latest scan results back to your repository as a PR. This is useful when the initial scan didn't trigger a PR (e.g., content was unchanged).

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 Integrations → GitHub 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`	Re-embeds the sitemap for tour generation
Push to `.navieo/docs/*.md`	Syncs doc pages to the dashboard
App installation/uninstallation	Updates connection status

Improving Selector Quality

For the best tour highlighting accuracy, add data-navieo-id attributes to key interactive elements in your code:

<button data-navieo-id="create-project">Create Project</button>
<input data-navieo-id="search-bar" placeholder="Search..." />

This gives Navieo a stable, high-confidence selector that won't break when CSS classes or component structure changes. It's optional — Navieo also uses id, aria-label, name, and semantic CSS selectors — but data-navieo-id is the most reliable.