Signing in to Navigara

# API Reference Source: https://docs.navigara.com/api-reference/introduction Integrate Navigara programmatically using the REST API. Full API reference documentation coming soon. ## Overview Navigara exposes a REST API (via gRPC-HTTP gateway) for programmatic access to all platform features. ## Authentication All API endpoints require authentication via Bearer token or API key. ```bash theme={null} # Session token curl -H "Authorization: Bearer " \ https://app.navigara.com/api/v1/organizations # API key curl -H "Authorization: Bearer navigara_" \ https://app.navigara.com/api/v1/organizations ``` ## Base URL ``` https://app.navigara.com/api/v1 ``` # Changelog Source: https://docs.navigara.com/changelog New features, improvements, and important changes to Navigara, newest first. New features, improvements, and important changes to Navigara. Newest first. This release rebuilds every list page and every detail page on one layout. Pull request reviews now count on the commits that produced them. ### Highlights #### One layout for every list page Developers, Repositories, Teams, Commits, and Checks now share the same anatomy. A title with one action sits on top. A control band holds search, filters, refresh, the column switch, CSV export, and row density. A panel holds the chart and the table. **Every numeric cell has a tooltip that defines the metric it shows.** #### One layout for every detail page Developer, repository, team, and day pages now use the same panels, the same metric strips, and the same loading behavior. **Each cell in a metric strip is a tab that switches the chart below it.** The repository page adds an average-per-period performance view and a deviation view. Pull request activity gets its own panel with sparklines and axis labels. #### Also in this release * Chart tooltips are shorter. They no longer repeat the numbers that the chart rows and the legend already show. * Charts across the application use the same axes, spacing, and tick labels. ### Important changes | What changed | What you will notice | What you can do | | ------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------- | | Pull request reviews now link to the commits that produced them. | Review activity appears on the source, merge, and squash commits of a merged pull request. Navigara reprocessed past pull requests, so developer and repository numbers can shift. | Compare periods inside the application. All periods use the updated calculation. | | Deleting a repository now removes the repository and all data derived from it. | Deleted repositories leave every list, count, and chart. Totals that counted them go down. | Nothing. Navigara cleans up repositories you deleted earlier. | ### Fixes * The Jira setup now includes the step that maps issue types to your work hierarchy. * Pull request sync now completes for Bitbucket repositories that hold no pull requests. * Self-hosted deployments sync pull requests when the analysis service runs an earlier version. * Summaries now complete on self-hosted deployments that use a slower language model. This release opens a free trial with no credit card. Navigara now classifies work into five categories: features, maintenance, tests, documentation, and fixes. ### Highlights #### Start free, with no credit card You can now create an organization and analyze up to **1,000 commits in 14 days** with no credit card. You add a card when you upgrade. The signup pages state both limits. #### Five work categories Navigara now classifies work into **features, maintenance, tests, documentation, and fixes**. Tests and documentation are first-class categories, so test work no longer counts as features and documentation no longer counts as fixes. Every chart, report, and summary uses the same five categories. ### Important changes | What changed | What you will notice | What you can do | | ------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------- | | Work classification uses five categories: features, maintenance, tests, documentation, and fixes. | Work mix figures change. Test files and documentation files now count in their own category instead of features or fixes. | Compare periods inside the app — all periods use the same five categories. | ### Fixes * Work mix cards now show one figure: the share of features. * You can now create a password account from an invitation link. * The password sign-in option now follows the setting of your deployment. This release adds a sandbox setting for repositories that hold experiments. Self-managed deployments can send provider traffic through a corporate proxy, and can verify the images they install. ### Highlights #### Sandbox repositories You can now mark a repository as a **sandbox**: an experiment, a playground, a hackathon, or a proof of concept. Navigara keeps the work on the repository page and leaves it out of organization and team totals. A chart that names the repository still includes it. The setting is in the repository edit dialog. No repository is a sandbox until you mark it. #### Provider traffic through your proxy Navigara now honors the standard `HTTP_PROXY`, `HTTPS_PROXY`, and `NO_PROXY` settings for issue tracker and Git provider traffic. A self-managed deployment behind a corporate egress proxy can reach a cloud issue tracker through the proxy, and an internal Git server directly. #### Verify what you install Every published container image now carries a **signature**, a software bill of materials, and build provenance. Each release publishes the exact image digests, and the deployment guide pins them. You can confirm that you install the same bytes Navigara released. ### Fixes * Pull request sync now follows a redirect that stays on your own server, so a renamed or moved repository keeps syncing. * An issue tracker sync now completes when one item is larger than the size limit. This release separates repository analytics from repository administration, and adds every selected repository in one step. Navigara now reads the full description body from every issue tracker. ### Highlights #### A separate view for managing repositories The **Repositories** page now shows analytics only: repository, tags, developers, and performance. A new **Manage** view holds administration, with five lists: available to add, all, active, disabled, and needs attention. You select rows across pages and act on them together. Adding a repository is a view over the same list, so onboarding and daily management stay the same. #### Add every selected repository in one step Navigara now adds a whole selection in **one request**. Each repository succeeds on its own, and the dialog names any repository it could not add. Adding 50 repositories now takes one round trip. #### Full descriptions from your issue tracker Navigara now reads the **full description body** of a project and an initiative, not the short summary. For Linear this is the project and initiative content. For Asana this is the project brief. A longer description gives the alignment analysis much more to read. #### Also in this release * A team lead now sees a clear message on a page their role does not open, instead of a redirect to the dashboard. ### Important changes | What changed | What you will notice | What you can do | | ------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------ | | Navigara restamps the metric rows of a developer when you change their role or team. | A list filtered by role or by team now shows the complete figures for that person. Filtered figures can rise. | Change a role or a team as usual. Navigara rebuilds the affected rows. | | Process checks read the full description body from every issue tracker. | Checks about description quality evaluate once more. An issue with a long body in Asana or Linear now passes them. | Run a full re-sync on the issue tracker connection, so stored issues pick up their bodies. | ### Fixes * Pull request sync now uses the base address you set for a self-managed GitHub or GitLab server. * Repository health now reflects whether Navigara can reach the repository. * The Objectives list now filters by parent objective faster. This release matches commits to Asana work by task ID. An invited user now accepts the invitation and signs in on one page. ### Highlights #### Asana matching by task ID Navigara now reads the **ID custom field** on your Asana projects. It matches a commit to an Asana task by that readable ID, such as `ABC-1234`. This is the ID your team already writes in commit messages. After you upgrade, run a full re-sync on the Asana connection. Existing tasks then pick up their IDs and align to your objectives. #### Accept an invitation and sign in on one page An invitation link now opens the standard sign-in page, with the invitation in context. You accept it with your identity provider: Microsoft, Google, GitHub, or GitLab. The account, the organization membership, and the invitation complete together in one step. Links you already sent keep working. #### Also in this release * Sign-in treats an email address the same, whichever letter case you type. ### Important changes | What changed | What you will notice | What you can do | | --------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------- | | Asana matching reads the task ID custom field from the project. | After a re-sync, alignment and objective figures for an Asana organization can rise. Commits that name a task ID now match that task. | Run a full re-sync on the Asana connection. Then compare periods inside the app. | ### Fixes * We strengthened the security of the platform. This release puts AI spend next to delivered value on every team and developer list, and replaces three activity counts on the Teams page with one measure of roadmap alignment. ### Highlights #### AI spend for every team and developer The Teams list and the Developers list gain an **AI spend / ETV** column. It shows the cost of AI usage for each unit of delivered value, with the total spend below it. A row with no recorded AI usage shows a dash rather than a zero, so an empty figure never reads as free work. Where AI usage cannot be matched to a person, a note under the table states how much spend sits outside the rows. #### Roadmap alignment on the Teams page Each team now shows the share of its delivered value that goes to the roadmap. The column uses the same calculation and the same label as the Roadmap alignment card on the dashboard, so both surfaces report the same number. A team with output but nothing on the roadmap shows `0%`. A team with no output shows a dash. #### Also in this release * Self-hosted installations now show a specific message when a license key is absent or cannot be verified, with wording an operator can act on. * Page-size options on every list now match the largest page the server returns. ### Important changes | What changed | What you will notice | What you can do | | ----------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------- | | The Teams page replaces PRs per developer, percentage reviewed, and cycle time with one Roadmap alignment column. | Those three columns no longer appear on the Teams page. | Read roadmap alignment for direction of work. Team detail still carries the delivery figures. | | A team row now rolls up every team below it in the team tree. | On an organization with nested teams, a parent team's roadmap alignment, performance, and AI figures can be higher than before, because they now include its sub-teams. | Compare periods inside the app — every period uses the same roll-up. | ### Fixes * Sign-in redirects now follow the address you opened, which keeps them correct behind a reverse proxy. * The root address takes you straight to your dashboard. * We strengthened the security of the platform. This release lets Asana customers map their own hierarchy onto objectives, and makes the quarterly report's comparisons and charts state exactly what they measure. ### Highlights #### Map your Asana hierarchy to objectives The connection wizard now offers Asana a mapping table. You choose which Asana level becomes an Objective, which becomes a Sub-objective, and which is ignored. Organizations that use Asana projects rather than portfolios can now set projects as their objectives and see alignment work end to end. After you save the mapping, run a full re-sync on the Asana connection so existing work picks up the new levels. #### Comparison periods you can read The AI Efficiency gauge compares against the same quarter last year when that quarter carries priced AI spend, and against the previous quarter when it does not. Every change now names the period it measured against, instead of always reading as a year-on-year figure. #### Chart detail that fits the date range The time picker now caps how fine a bucket you can pick for a long date range, so a chart stays readable. A bucket that is too fine for the selected range is disabled and explains why. Typed input and shared links coarsen the bucket automatically instead of rendering hundreds of bars. #### Also in this release * Performance charts name the OSS Index on the plot, shade the area beyond it, and show each bar's share of it in the tooltip. * Charts label weeks with their calendar week number. ### Important changes | What changed | What you will notice | What you can do | | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | | The Objectives page reads alignment from the same server-side calculation as the dashboard, over the whole selected period rather than the visible page. | The alignment percentage and the aligned and unplanned split on the Objectives page can shift slightly, and now match the dashboard. | Compare periods inside the app — both pages use the same calculation. | | **Self-hosted:** the root login credential is now one-time, carries a required issuer, type and id, and is sent to `/impersonate` as a form POST rather than in the URL. | A root login link of the form `https:///impersonate?token=...` returns 405, and a credential signed by an older script is refused as invalid or expired. | Replace your root-login script with the current one in [Full on-premises → Product Setup](/deployment/full-on-premises#9-product-setup). | ### Fixes * The OSS Index line and its shaded area show and hide together from the chart legend. * Chart value axes land on round numbers for every tick. This release deepens project reporting, makes the quarterly report board-ready, and gives self-hosted operators full control over who can sign in as root. ### Highlights #### Project detail shows where the work comes from A project inside an objective now shows how much work flows into it, split by issue and by developer. The objective view above it gains the same per-project breakdown. Both views keep the split, share, and delivered value figures you already see on the objectives overview. #### Board-ready quarterly reports The quarterly report now states where its numbers come from. A footer shows when the report was generated, the date the data runs through, the applied scope, and the benchmark cohort with its effective date. New print and share actions turn the report into a PDF, with every chart data table included. AI efficiency gains a gauge against last year's cost per unit of delivered value. #### Full control of root access on self-hosted installations Self-hosted operators can now set `DISABLE_NAVIGARA_SUPPORT_ACCESS=true` to make their own administrator key the only key that can sign in as root. Navigara refuses to start if the setting is enabled without an administrator key, so an installation cannot lock itself out. License verification is unaffected. #### Also in this release * The dashboard, developer lists, and objective pages load faster. * Charts, buttons, and loading indicators follow one consistent visual scale across the app. ### Important changes | What changed | What you will notice | What you can do | | ------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- | | AI spend per unit of delivered value now uses one calculation, computed over the full selected period. | The headline ratio on the AI spend view and on a developer's detail view now match, and can differ slightly from the previous figure. | Compare periods inside the app — every view uses the same calculation. | | Commit analysis scores changes that only touch declarations, constants, or values, such as a changed threshold or a rewritten query. | Performance figures for past periods can shift upward where such changes were previously scored as cosmetic. | Compare periods inside the app — all periods use the same calculation. | | The list of billable developers now needs an owner or administrator role. | A member or viewer sees the billable developer count, but not the names and email addresses. | Ask an organization administrator for the roster when you need it. | | Self-hosted analysis records commit times in coordinated universal time (UTC) end to end. | On a self-hosted installation outside UTC, commit times and the periods built from them line up with your Git history. | Run a re-analysis for repositories analyzed before this release to refresh their stored times. | ### Fixes * Pages and lists show a loading indicator until their data arrives, instead of a zero or empty state. * A list emptied by a filter now says that no results match, and keeps the filter controls in place. This release makes reports decision-ready and gives every role the right view of the data. Executive briefings now lead with delivered value and separate real delivery risk from backlog debt. Team leads see their own teams, Checks enters Beta with per-organization settings, and you can manage your subscription yourself. ### Highlights #### Team-scoped access for team leads The team lead role now scopes every view to the teams a person leads. Commits, metrics, objectives, developers, team members, and checks all follow the same scope. Organization-wide objectives stay visible to everyone, so leads keep the full picture of what the organization aims at. #### Decision-ready executive briefings Weekly and monthly briefings now have distinct jobs. The weekly briefing covers operations. The monthly briefing covers strategy. Both lead with delivered value, then show the work mix, backlog movement, and how risk changed since the last period. Briefings separate delivery risk from backlog debt, so aging low-priority work no longer reads as a delivery problem. AI spend appears as total cost and as cost per unit of delivered value. #### Redesigned quarterly report The quarterly report has a new executive summary. Performance reads against a stable benchmark scale with a target marker, so the gauge means the same thing every quarter. One color palette covers performance, AI, alignment, maintenance, and fixes across every chart. Each change states the period it compares against, and the quarter selector, labels, and links behave consistently. #### Checks in Beta, with per-organization settings Checks is now available in production as a Beta feature. A new Checks page in Settings lets you turn each check on or off and tune its thresholds, such as how long a pull request may stay open or wait for review. The occurrence list supports search and paging, and triage follows a familiar filter, group, and resolve pattern. #### Manage your subscription yourself Billing settings now include a button that opens a secure payment portal. There you can update your card, view invoices, and cancel. At each renewal, Navigara counts the developers billable for the coming period and bills that count, with no mid-period adjustments. If a payment does not go through, you keep a grace period to recover, and the portal stays reachable throughout. #### Also in this release * The accepted company context now appears in Settings, and each briefing records the context version it used. * Dashboards, repository pages, and developer pages load faster. * The dashboard and the Objectives page share one Objective alignment chart, with stacked bands and a percentage view. * Filters across the app share one neutral pill style. ### Important changes | What changed | What you will notice | What you can do | | ------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------ | | Navigara now marks a pull request as AI-assisted from the commits it contains. | More pull requests read as AI-assisted, including ones merged as a single squashed commit. Your AI-assisted share can rise. | No action needed. Pull requests update as they are analyzed. | | Per-file change classification uses an updated model prompt. | The split between growth, maintenance, and fixes can shift for newly analyzed work. | Compare periods inside the app. All new analysis uses the same classification. | | Developer monthly summaries build their comparison baseline from months with activity, and state the recent trend. | Monthly summaries describe trends differently. A month can read as a steady run rate instead of a standout. | Generate a summary again to see the updated wording. | ### Fixes * Pages show skeleton placeholders while they load their data. * Performance values use the same formatting and unit label on every page. * The processing status dashboard counts scheduled re-checks separately from work that is still pending. * We strengthened the security of the platform. ### Highlights #### Jira connections with scoped API tokens You can now connect Jira Cloud with a scoped Atlassian API token. Navigara detects which token type you supply and uses the matching Atlassian endpoint for validation and sync. Classic tokens keep working as before. #### AI spend is generally available The AI spend view is now generally available, and its Beta label is gone. Every organization can use it to compare weekly cost against weekly performance. #### One consistent page layout Pages across the app share one heading style, one panel container, and one empty-state pattern. Page titles, dialog titles, and confirmation messages use the same sentence-case wording everywhere. #### Also in this release * Empty states tell you whether there is no data yet or whether your filters returned nothing. * A section that cannot load its data shows an inline message with a retry action. ### Fixes * Charts include benchmark lines when they scale the vertical axis, so the benchmark stays visible. * Refreshing the Discovered repositories list updates it in one step. * We strengthened the security of the platform. ### Highlights #### Bitbucket Cloud connections Adding a Bitbucket Cloud connection with an API token now validates and syncs pull requests, including for workspace-scoped tokens. #### Consistent status colors everywhere Objective status, roles, and other status indicators use the same colors and badge style across every page. A status looks the same wherever you see it. #### Also in this release * Percentages and change values across the app display with consistent formatting. * Currency and large-number values display with consistent formatting throughout the app. * Terminology across the app is more consistent, covering developer, organization, issue, email, and AI spend labeling. ### Fixes * Mark retry and dismiss actions now include more detail in their audit history. ### Highlights #### Live AI efficiency in quarterly reports The AI efficiency card in the quarterly report now shows a live figure for spend per unit of output. It clearly shows when there is no AI usage yet, when usage exists but has no cost attached, and when spend exists but no output was delivered. #### Redesigned executive summary The dashboard executive summary card has a refreshed look. It includes a clearer loading state, a draft label for briefings covering a period still in progress, and a one-click way to generate a briefing on demand. #### Consistent filters and toolbars Filters and search on the Repositories, Developers, and Teams pages, and the global top bar, now follow one consistent style and layout. This makes them easier to find and use. #### Also in this release * In-app setup is now available to everyone, guiding new organizations through connecting their tools. * The "How is performance evolving" dashboard card was redesigned with clickable views. * Navigara now measures tool calls per message to give a clearer picture of AI tool usage. * The Aliases table in Settings now keeps its row actions visible within the page. * We strengthened the security of account sign-in. ### Important changes | What changed | What you will notice | What you can do | | ----------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------ | | The quarterly report's team activity, average headcount, and role breakdown now use a more precise, week-by-week calculation. | These figures for past quarters can shift slightly. "All Developers" now always shows a full role breakdown. | Compare quarters inside the app. All quarters use the same calculation. | | The Add Repository dialog no longer offers a manual URL entry option. | You can add repositories only from the Discovered list. This keeps them linked to a connected integration. | Use the Discovered tab to add repositories. Connect a provider first if none are discovered yet. | ### Fixes * Analysis of code changes now keeps paired test information intact when a repository is re-analyzed. This release makes it easier to get started with Navigara on your own and to understand your delivery at a glance. New executive briefings and on-demand reports bring your objectives, work, and costs together in one place. ### Highlights #### Self-serve signup and free trials New organizations can now sign up and start using Navigara on their own, without waiting for manual activation. The setup flow guides you through connecting your code and task management. Each step advances automatically as it completes. If your plan includes a free trial, an in-app banner shows how many days remain, and a reminder email arrives before the trial ends. #### Executive briefings and on-demand reports The dashboard now opens with an executive briefing. It leads with your objectives, then shows aligned and untracked work, costs, and notable team activity. Each repository, developer, and team has a redesigned Reports section in the same briefing style, with a period navigator to browse every completed period. You can generate any report on demand with a single click. Briefings also refresh automatically after you connect a task management tool, so new objectives appear right away. #### Also in this release * A new usage view shows your plan and how much of your commit-analysis limit you have used, with a trial countdown and a page that lists exactly which developers count toward billing. * The Checks page now uses one consistent layout and links each finding to its source commit, pull request, or issue. * Chart legends are now interactive: select an item to show or hide that series. * Developer aliases let you group several email addresses under one developer profile. ### Important changes | What changed | What you will notice | What you can do | | --------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------- | | Trial and paid plans now include a commit-analysis limit. | When your organization reaches its limit, new commit analysis pauses. The rest of Navigara stays available. | Upgrade your plan to raise the limit. Your existing data and dashboards stay visible. | ### Fixes * The Add Repository dialog now closes automatically after you add repositories, and lists newly discovered repositories as they are found. * Developer detail pages now list only repositories with activity. * Objective charts now include periods that have no activity. * You can now connect Asana and load your workspaces during setup. ### Highlights #### Redesigned AI spend insights The AI spend view now matches weekly cost against weekly performance across developers, teams, tools, and models. You can see cost and value side by side. Developers get a dedicated detail view. Rows are fully clickable, and tools share a consistent legend across charts. #### Light theme for sign-in and onboarding Sign-in and onboarding now use a clean light theme that matches the rest of the app. Text is clearer, buttons are consistent, and contrast is improved. #### Switch between quarters in the quarterly report The quarterly report now includes a quarter selector. You can review recent quarters instead of only the latest one. Every section, including baselines, weekly charts, teams, and objectives, updates to match your selection. #### Also in this release * The Key metrics board on the dashboard has a refreshed layout, with progress-colored trend bars and clearer period totals. * AI spend records now include a cache-aware cost estimate for supported AI coding tools, for a more complete spend picture. ### Important changes | What changed | What you will notice | What you can do | | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------- | | Pull request cycle time, throughput, review coverage, and quality headlines on reports now use the full period instead of averaging weekly values. | Some headline figures may shift slightly compared to earlier periods. Missing periods show as unavailable instead of showing 0. | Compare periods inside the app. All periods now use the same calculation. | | The Key metrics board now calculates alignment share, AI-assisted share, and cost-per-performance as true totals across the selected window, rather than an average of weekly percentages. | Some percentages, including AI-assisted share, may read differently, especially for windows with uneven weekly activity. | Use the in-app window figures going forward. They reflect the full period. | | Objective lists and quarterly reports now return every objective for organizations with more than 50, instead of stopping at 50. | Organizations with more than 50 objectives will see additional objectives in lists, reports, and alignment figures. | No action needed. The fuller list appears automatically. | ### Fixes * You can now edit the host path and token name on an existing token-based connection, instead of only rotating the token. * Charts now render every value on the vertical axis, so no tick is skipped. * The processing status dashboard now refreshes automatically after you retry or dismiss an item. * We strengthened the security of the platform. ### Highlights #### Refreshed dashboard The dashboard now opens on the last 12 months by default. Team rows show alignment and AI spend alongside performance. Objectives render as shaded area charts, and the top 20% share callout shows what percentage of total performance it represents. #### Asana task linking by ID Navigara now recognizes Asana's human-readable task IDs (for example `IDP-4355`) in commit messages. Commits and Asana tasks line up automatically, not just from the underlying task link. #### Safer connection setup The connections page only shows sign-in options that are fully set up on your account. You always land on a working setup step. #### Also in this release * List pages across the app now share a consistent panel layout and color palette. ### Important changes | What changed | What you will notice | What you can do | | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------- | | Performance totals and averages on developer, team, and repository pages now use one consistent calculation everywhere. | Some totals and benchmark lines may shift slightly, and now always agree with the same number shown in lists and charts. | Compare periods and entities freely — the same calculation is used on every page. | | A team's total performance now includes people who contributed to the team's work during the period, even if they have since moved to another team. | Team totals now match the sum of the rows shown below them. Former developers appear with a "Former" label. | No action needed. | | AI detection now also recognizes commits authored directly by an AI coding agent, not only commits with an AI co-author, using an updated detection model. | Some commits from AI coding agents may now be marked as AI-assisted. Existing commits update the next time they are re-analyzed. | No action needed. | ### Fixes * Jira: objective and sub-objective changes now update the alignment status of all related commits, including ones several levels down. * Jira: on-premises Jira connections now keep separate identities, so two on-premises instances are never mixed together. * Reported AI tool usage and spend from on-premises analysis is now calculated consistently over time. ### Highlights #### Connect Asana and Linear Navigara now connects directly to Asana and Linear with a one-click sign-in flow. For Asana, you can choose which workspace or workspaces to sync, so multi-workspace teams get exactly the projects and tasks they need. #### Flexible email delivery Organizations running Navigara on their own infrastructure can now send password reset, invitation, and welcome emails through any standard email provider, using a simple configuration. #### Also in this release * Cloud infrastructure monitoring alerts help the Navigara team keep the platform reliable. ### Important changes | What changed | What you will notice | What you can do | | -------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------ | | AI-detection now uses a more conservative threshold, favoring precision over recall. | Fewer commits are flagged as AI-assisted; flagged commits are held to a higher confidence bar. | No action needed. Detection continues to improve in future releases. | | Commit scoring now credits developer effort more accurately for new files, new functions, and cross-file code reuse. | Work-type scores for some commits may shift slightly compared to earlier periods. | Compare periods inside the app — all periods use the same updated calculation. | ### Fixes * Organization owners, admins, members, and viewers can now access the Connections page from Settings. ### Highlights #### Refreshed visual design Navigara has a new look across the app, including dashboards, settings, and sign-in. Buttons, cards, menus, and other controls use a refined color palette, softer shadows, and tighter spacing in both light and dark mode. ### Important changes | What changed | What you will notice | What you can do | | ----------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- | | The objective alignment KPI on the dashboard summary uses the same alignment calculation as the detailed alignment charts elsewhere in the app. | The objective alignment percentage on the dashboard may shift, and now shows as two lines (key aligned and aligned) instead of one. | Compare periods and views inside the app. The dashboard summary and detail charts use the same calculation. | ### Fixes * Objective alignment figures on the dashboard summary stay consistent with the alignment charts shown elsewhere in the app. Navigara v0.12.1 refreshes the dashboard and team views, and improves chart accuracy across performance pages. ### Highlights #### Dashboard summary and teams The dashboard summary now shows performance, objective alignment, and AI augmentation as trend lines. Each trend line has a trend chip comparing the start and end of the period. The Developers section is now a Teams section. It shows your top and bottom teams by performance, with a link to each team's page. #### Performance chart views for teams and developers Team and developer pages now have clickable summary cards. Use them to switch the chart between alignment mix, work mix, average member performance, and AI augmentation. AI spend now shows as spend per unit of value delivered, with total spend shown alongside it. #### Team hierarchy Sub-teams and parent teams are back on team pages. A breadcrumb shows each team's place in the hierarchy. A picker lets you assign sub-teams when creating or editing a team. #### Also in this release * The Developers list filters are simpler: search by name or email, filter by team, or by probation status. * Developer detail pages now show the same clickable performance charts available on team pages. ### Fixes * The team edit page now opens. * The "Top 20% Sum" trend line on the dashboard timeline chart now renders alongside its legend and summary value. * Chart Y-axes on developer and team pages now scale closer to the actual data, removing excess empty space above the highest value. * Table row hover is now visible in light mode. ### Highlights #### Find and re-enable disabled repositories Repositories you disabled from analysis previously disappeared with no way to bring them back. A new Disabled tab next to your repository list shows every disabled repository and lets you re-enable it with one click. #### A guided setup wizard for task tracking connections Connecting Jira, Linear, or another task tracker now walks you through picking which projects to sync. It also shows how issue types map to objectives, sub-objectives, and issues. The same wizard supports every provider. Reopening it later shows your saved settings instead of resetting them. #### Multiple connections per AI tool You can add more than one connection for the same AI assistant. For example, you can set up separate connections for different backends or departments. Each connection gets its own setup view and can be removed independently. #### Also in this release * Team and developer pages now show extra performance and alignment detail cards. * The commits page highlights pull-request metrics, including merged count, average cycle time, and review coverage, and makes AI-assisted commits easier to spot. * The AI spend page is reorganized around cost, with a per-developer breakdown, pagination for large teams, and a drill-down view for individual developers. * The settings page now shows when each API token was last used. * Reports has graduated from beta and is now generally available. * The toolbar shows a live indicator while your organization's data is being processed. * You can compare a period against its previous period directly in custom metric queries, and build custom calculated measures from existing ones. ### Important changes | What changed | What you will notice | What you can do | | --------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------- | | Commit scoring recognizes renamed files by their prior history and excludes generated and minified code from scoring. | Performance scores for past and future periods can shift, especially for repositories with renamed files or generated code. | Compare periods inside the app. All periods use the same updated calculation. | | Large commits are now fully analyzed. | More commits contribute to performance metrics, which can change historical totals for repositories with large commits. | No action needed. Metrics automatically reflect the fuller analysis. | ### Fixes * Navigara now shows a maintenance page instead of signing you out when it briefly cannot reach the server. * Developer reports now support the quarterly view. * The commits page keeps your repository filter selected when you also filter by developer. * The developers page keeps your filters and page position when you change the time range. * Switching organizations now loads all your organizations the first time you select "Show more". * Strengthened the security of the password change flow. ### Fixes * Pull request metrics in reports now stay up to date and scoped correctly after team or hierarchy changes. ### Highlights #### More accurate average-per-developer metric The average-per-developer figure now sums each week's average within a period. Larger periods, like a month or quarter, stay proportional to their weeks. A developer who joins partway through a longer period no longer skews the average for everyone else. #### Consistent numbers across dashboard and reports The dashboard summary and KPI cards now use the same average-per-developer calculation as quarterly reports. The numbers match everywhere you see them. ### Important changes | What changed | What you will notice | What you can do | | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------- | | The average-per-developer calculation now sums weekly averages instead of using a single period-wide rate. The dashboard uses the same calculation as quarterly reports. | Average-per-developer figures for months and quarters may shift slightly from previous values. Dashboard figures may also differ slightly from before, while matching quarterly reports. | No action needed. All periods and pages now use the same, consistent calculation. | ### Fixes * The quarterly report now loads when no team roles are configured, showing a clear message instead of staying on a loading state. ### Highlights #### AI tool usage and spend, per developer Navigara now ingests usage telemetry from AI coding tools. It attributes tokens and spend to the developer who generated them. You can track AI adoption and cost person by person, not just organization-wide. #### Refreshed dashboard overview The dashboard overview now shows Performance, AI Augmented, and Alignment side by side. It runs on an updated metrics engine for faster, more consistent numbers. #### Also in this release * The Repositories page replaces automatic polling with a manual Refresh button, so you control when the list updates. * Adding a developer to a new team now warns you first if they already belong to another team, since the move ends their current membership. * Directory sync (SCIM) now supports value-path filtering for Microsoft Entra ID provisioning. * Metric-backed list views support entity search filters and pagination for faster browsing on large organizations. ### Important changes | What changed | What you will notice | What you can do | | ---------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------- | ---------------------------------------------------------------------------------- | | Total commit counts for repositories now use the verified count from analysis instead of an approximation. | Commit totals shown for some repositories may shift slightly. | No action needed — the new totals are more accurate and consistent across the app. | ### Fixes * Editing a repository that was previously stopped now resumes its analysis automatically. * Developer lists and filters now show the correct team for each developer. * Team membership lists no longer show duplicate or outdated entries for developers who changed teams. ### Fixes * Team pages now open when the team name includes spaces or accented characters. * Team membership history no longer shows duplicate entries when someone rejoins the same team on the same day. * Signing up now returns a clear "already registered" message when the email address is already in use, even when multiple sign-up attempts happen at the same time. Navigara v0.11.3 brings a redesigned time picker, a full membership history for teams, and richer executive summary gauges on reports and dashboards. ### Highlights #### Redesigned time picker The date range picker now uses simple period chips (day, week, month, quarter, year) with quick presets like "Last 12 weeks" or "Last 8 quarters". A new "complete periods only" toggle lets you exclude the current, still-in-progress period from your view so you are always comparing full periods. The default view is now the last 12 complete weeks. #### Team membership history Team detail pages now include a membership history panel showing every developer who has ever been on the team, past and current. Filter by name or email, and open a developer's role directly from the list. #### Executive summary gauges Reports and dashboards now show Performance, Objective alignment, and AI efficiency as clear gauge cards, each with a year-over-year trend indicator. Reports also gained an outcomes section highlighting the quarter's top objectives with supporting evidence, and a quality and governance summary covering pull request throughput, review coverage, and cycle time. #### Also in this release * You can now pause analysis for an individual repository from its settings, without removing the repository. * We strengthened the security of the platform. ### Important changes | What changed | What you will notice | What you can do | | --------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------- | --------------------------------------------------------------------------------------- | | Team membership shown in past period summaries now reflects who was on the team at that time. | Historical summaries for teams may show different developers than before. | Compare periods inside the app. All periods now use the same, time-accurate membership. | ### Fixes * Connecting a tracker or issue integration now shows a clear message when a connection is temporarily rate limited. * Adding or editing a team member now shows a clear error message if the request cannot be completed. * Searching for a developer to link now returns results faster. ### Highlights #### Bulk add team members You can now add several developers to a team in one step. Search and multi-select developers, or paste a list of email addresses. Preview each person's current team assignment. Set a shared start date, with a per-row override when needed. #### Also in this release * Team pages stay in sync everywhere. Changes made from the Developers page are immediately reflected on the Teams page. * API key errors are now shown clearly on the Tokens page, with a retry option. ### Important changes | What changed | What you will notice | What you can do | | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------- | | Refined the calculation that measures how much a code change alters a developer's work, used in performance scoring. Mechanical, repetitive edits, like adding the same annotation across many files, are recognized more accurately. Simple variable renames are distinguished from more substantial logic changes. | Historical and new performance scores may shift slightly for commits affected by these patterns. | Compare periods inside the app. All periods use the same updated calculation. | ### Fixes * Improved the reliability of analysis processing for organizations with a large volume of pending work, so results keep flowing smoothly. * Improved reliability of the reporting connection setup flow with clearer error messages. ### Highlights #### Clearer issue tracker sync status The connected issue tracker card now shows "Last synced" as a relative time, with the exact time available on hover. A new **Force sync** button lets you trigger an immediate refresh instead of waiting for the next scheduled sync. ### Fixes * The **Add repository** button on the Repositories page now appears reliably on every page load. Navigara v0.11.0 makes team history and organization identity easier to manage, adds fast global search, and improves several existing surfaces. ### Highlights #### Team membership history Team pages now show a full history of which team each developer belonged to and when. You can add, edit, or delete historical or active membership periods. Changing a developer's team now asks for the transition date instead of assuming today. #### Global command search Press Cmd/Ctrl+K anywhere to search objectives, teams, developers, repositories, and commits. You can also jump straight to a page. #### Also in this release * Organizations can rename themselves from general settings. * CapEx datapack exports include richer issue metadata and links. * Organizations can set a default analysis start date, used when a repository does not specify one. * Repository connection setup includes clearer local setup guidance for Rancher Desktop users. ### Important changes | What changed | What you will notice | What you can do | | ------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------- | ------------------------------------------------------ | | The Architecture feature (architecture analysis and feature catalog) has been removed from the product. | The Architecture page and related settings are no longer available. | No action needed; other analysis views are unaffected. | ### Fixes * The file changes table respects your selected metrics view consistently. * The commits page keeps the correct total count while paging through results. * Search fields handle special characters correctly when filtering results. * API key names are validated for length to prevent overly long values. * Directory sync (SCIM) is more reliable when mapping and syncing user attributes. Revoking a sync token can be repeated safely. ### Highlights #### Team hierarchy Teams can now be organized into a tree, with parent teams and sub-teams. Create sub-teams when you create a team, or move a team under a new parent. The teams list shows the full structure with a clear indented view. Metrics for a parent team now include all of its sub-teams, so a leader can see their whole organization at a glance. #### CapEx report export The CapEx report now has an Export CSV button. It downloads one row per developer per month for the selected date range, with hours and CapEx percentage. The file opens directly in Excel or Google Sheets. #### SCIM connection management Organization admins can now create, list, and revoke SCIM tokens from Settings. This supports identity-provider provisioning. #### Also in this release * Error messages and page refresh behavior are clearer across Repositories, Teams, and Explore, so failed actions are easier to notice and retry. ### Important changes | What changed | What you will notice | What you can do | | ----------------------------------------------------------------- | ----------------------------------------------------------- | ------------------------------------------------------------------ | | AI-assisted commit detection uses an updated classification model | Commits may be classified differently as AI-assisted or not | No action needed; classifications continue to update automatically | ### Fixes * Historical summaries now load their status and totals reliably. * Repository and benchmark pages refresh automatically after you delete, stop, or reset an analysis, so the list reflects the latest state. * Accepting a team invitation now keeps an active organization selected. * Analysis results are preserved more reliably if processing is interrupted partway through. ### Fixes * Team management shows clear confirmation and error messages when you create a team, update a team, add members, or remove members. ### Highlights #### Team visibility on the developer page The developer detail page now shows a Team card. You can see which team a developer belongs to without switching pages. Organization owners and admins can assign a team directly from this card when one is not set yet. #### Also in this release * Sync status for Linear now distinguishes an organization that has never connected Linear from one that connected but has not synced yet. ### Important changes | What changed | What you will notice | What you can do | | ---------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------- | | Engineering Throughput Value (performance scoring) no longer applies a fixed minimum impact value to every file in a commit. | Historical performance scores can shift, especially for small or trivial commits that previously clustered at the same low value. The overall distribution of scores is now smoother and more representative of actual contribution size. | Compare periods inside the app. All periods use the same updated calculation. | ### Fixes * Deleting a team now asks for confirmation before removing it, to help prevent accidental deletions. * Benchmark reports now show grouped and aggregated results. ### Highlights #### Repository connection health Navigara now detects when a repository connection loses access, for example because of expired credentials or an unreachable repository. Affected repositories show a clear status. You can retry the connection with one click to restore analysis. #### Also in this release * Team performance metrics automatically refresh when a developer joins or leaves a team. * Role filters on the Developers and Reports pages now include every matching developer, even for large teams. ### Important changes | What changed | What you will notice | What you can do | | ------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------- | -------------------------------------------------------------------------- | | Team metrics now reflect which team a developer belonged to at the time the work was done, instead of their current team. | Historical metrics on team pages may shift slightly for developers who changed teams. | No action needed. Team pages automatically show the corrected attribution. | ### Fixes * Objective pages now consistently show performance charts and breakdowns. * Performance reports show refreshed data with corrected work-classification percentages. ### Highlights #### Smoother sign-in and organization switching Signing in with email or a single sign-on provider now takes you straight to your dashboard with the right organization selected. Switching organizations is instant. #### New AI provider option Organizations can now connect Navigara to Claude and GPT models through Azure AI Foundry, in addition to the existing provider options. #### Also in this release * Access controls now limit repository tag changes, developer identity changes, and developer merges to organization admins. ### Fixes * Dashboards now display up-to-date data across all views. * Commit history analysis now respects each repository's configured start date. Large, long-running repositories analyze faster and stay within the intended time window. * Updating a Git access token now automatically refreshes repository discovery. Deleting a token now warns you when active repositories depend on it. ### Highlights #### Renamed performance unit to Engineering Throughput Value (ETV) The quarterly performance report now presents your score as Engineering Throughput Value (ETV). This aligns naming across the quarterly report and the performance whitepaper. The report also adds an Activity measure showing how actively engaged your team was each quarter, with clear color bands and a worked example. #### Refreshed and expanded performance whitepaper The cross-organization performance whitepaper now shows independent scales per organization. Smaller teams are no longer flattened by larger ones. The whitepaper also adds a cohort breakdown table and a full appendix listing every repository analyzed. #### Also in this release * Team, seniority, and role selections on the Developers page stay applied immediately after you make them. * Team member lists and additions are more reliable. * The dashboard summary (active developers, average performance, active repositories) loads faster. ### Fixes * We strengthened access controls around organization settings. ### Highlights #### Cleaner repository and team pages Repository and team detail pages now show cleaner, more relevant information. Outdated panels have been removed. #### Consistent developer counts Developer counts now match everywhere they appear on a repository page. ### Important changes | What changed | What you will notice | What you can do | | ------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------- | | Weekly activity charts now align time buckets to your account's configured time zone. | For organizations outside UTC, some past weekly charts may show different values as data is grouped into the correct time window. | No action needed. Charts automatically reflect the new alignment. | ### Fixes * Commit history catches up automatically after an analysis run is interrupted, so no commits are left unprocessed. * Developer counts on repository pages are consistent across all views. * Team detail pages no longer show an unrelated repositories section. * Repository detail pages no longer show an outdated project information panel. ### Highlights #### License expiration banner Self-hosted organizations now see a banner in the sidebar as their license approaches expiration. It shows a clear countdown, and a follow-up notice during the grace period after expiration. Cloud organizations are not affected. #### Also in this release * Dashboard pages load faster. They combine several data requests into fewer round trips. ### Fixes * Analysis of very large repositories continues from where it left off if interrupted. ### Highlights #### Regenerate summaries for your whole organization You can now regenerate developer summaries for your entire organization from Settings. Previously you could only do this one repository at a time. ### Fixes * The discovered repositories page now loads faster and shows accurate result counts while paging through results. * Pull request data now loads for public repositories outside your connected GitHub organization. * Newly created teams now appear immediately in every team selector on the page, without needing a refresh. ### Highlights #### Stronger account security Navigara now requires stronger passwords when you sign up, reset your password, or accept an invitation. A checklist shows in real time whether your password meets the requirements as you type. Password reset requests are rate-limited, and email addresses are validated before an account is created. #### Faster repository analysis Analysis of larger repositories now scales horizontally. Organizations with heavy analysis workloads see faster processing. Source code parsing is also more efficient, improving analysis speed and reducing memory use. #### Also in this release * Invitations and organization access use stronger validation. * Repository selection during setup supports pagination and filtering by provider. ### Fixes * Page numbers on the commits list stay accurate when navigating between pages. * The probation period notice disappears automatically once the probation period ends. ### Fixes * Signing in now takes you to your dashboard, even if you also have a personal organization from onboarding. * Objectives you do not have permission to view now show a clear message instead of a not found page. ### Highlights #### Clickable commit references Commit references in reports and the period detail view are now clickable. Select one to jump straight to the source commit. ### Fixes * Analysis of large repositories now completes more consistently. ### Highlights #### Faster search across selectors Repository, developer, and user pickers now search on the server as you type. Selectors open instantly and results update as you search. #### Sortable, paginated file changes The file changes table on commit and developer pages supports sorting by complexity, engagement, and performance. Pagination handles commits that touch many files. You can also expand a commit's file changes directly from the developer page. #### Streamlined sign-in Login, invitation, and onboarding pages now show only the sign-in options your organization has configured. Icons and loading states are consistent across all three. #### Also in this release * Repository analysis skips example folders, dependency manifests, and changelog files, focusing on your actual source code. * The date picker on the add and edit repository dialogs is consistent across both, and opens on the month of the currently selected date. ### Important changes | What changed | What you will notice | What you can do | | ----------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------- | | The Projects feature (project filters and the "Performance by Project" chart) has been removed. | Project-based filtering and charts no longer appear on the repositories and objectives pages. | Use the repository and developer filters that remain in place for the same views. | | The "Waste" metric label is now called "Fixes" throughout the app. | Dashboards, charts, tooltips, and settings show "Fixes" instead of "Waste". | No action needed. The underlying metric is unchanged, only the label is new. | ### Fixes * Re-inviting someone with an already-pending invitation refreshes their invitation rather than showing an error. * The edit repository dialog keeps your changes in place while data refreshes in the background. * Creating a team with a name that is already in use shows a clear error message. * Team names are limited to 255 characters, consistent across the app and API. * Setting a developer's primary email shows a confirmation toast. ### Highlights #### Bitbucket Server and Data Center support Organizations using a self-hosted Bitbucket Server or Data Center instance can now connect it the same way as Bitbucket Cloud. This includes pull request history, comments, and approvals. #### Licensing for self-hosted deployments Self-hosted deployments now include a license key system. Administrators can see trial and license status directly in the product. #### CapEx reports A new Reports section in the sidebar includes a CapEx report page with chart visualization. This gives finance and engineering leaders a clearer view of capitalized development effort. #### Also in this release * Invite links can now be copied directly from the invite dialog and from the pending invitations table. * The commits page now uses consistent pagination controls. * Commit lists can now be filtered by developer. * Connection setup now suggests the correct address format for host fields. * Accepting a team invitation now supports all available sign-in providers. ### Fixes * We updated underlying dependencies to strengthen platform security. ### Highlights #### Manage membership across every organization Platform administrators can now manage membership across every organization. They can assign the owner or admin role and remove any member. Organization-level admins keep their existing, more limited permissions. ### Fixes * The growth metric now displays its color clearly in all cases. Navigara v0.10.0 brings a role-aware view of your organization, more control over which repositories count toward your metrics, and better root-cause tracing for fixes. ### Highlights #### Role picker with role-filtered metrics You can switch between roles, for example engineer or manager, from a global picker. Every page, including dashboards, summaries, and reports, filters its metrics to match the selected role. This makes it easier to see the numbers that matter for a specific perspective. #### Repository settings and metrics exclusion Each repository now has a settings panel where you can exclude it from organization-wide metrics. When you turn on exclusion, Navigara recalculates all affected metrics in the background so dashboards and reports stay consistent. #### Deeper root-cause tracing for fixes Navigara traces fixes back to the commit that originally introduced the issue being fixed. This works even when the fix and the original change touch different files or functions. It gives more accurate context on developer summaries and commit history. #### Also in this release * Added a quarter option to the time-bucket selector, presented as a dropdown. * Repositories are shown with their owner and repository name instead of a raw URL. * Added Navigara tools for AI assistants, through MCP, to list repositories and objectives, fetch summaries, and query metrics directly. ### Important changes | What changed | What you will notice | What you can do | | ------------------------------------------------------------------------ | ------------------------------------------------------------------------------- | -------------------------------------------------------------------------------- | | Code complexity scoring uses a more precise, per-symbol analysis method. | Complexity-related scores can shift slightly for past and future periods. | Compare periods inside the app. All periods use the same updated method. | | Engagement metrics weigh imports and non-code files more accurately. | Engagement scores may change slightly for affected developers and repositories. | No action needed. The new values are more representative of actual contribution. | ### Fixes * Strengthened access controls around organization membership, repository management, and administrative actions. * Invitations can no longer be sent twice to the same address for an organization. * Settings pages show a clear error and revert your change if a save does not go through. * The developers list includes all available time-bucket sizes. ### Highlights #### AI-augmented badge on commits The commits list and commit detail page now show a badge on commits identified as AI-augmented. This applies when AI detection is enabled for your organization. #### Architecture overview The Features page is now Architecture. It has a filter bar for searching by name, category, and team, and a clearer table layout. #### Also in this release * Repositories now rank by total performance, so the sort order matches what is shown on the page. * Search when adding a repository now matches names anywhere, not only at the start, and shows how many results are available. ### Fixes * Editing a repository's analysis start date to an earlier date now updates its metrics and summaries to match. * Large charts on the commit detail page render smoothly. * The date picker in Add Repository shows the correct month. * Search in Add Repository waits briefly before searching, and no longer overwrites your results while a sync is in progress. * Sync and connection errors in Add Repository are shown so you know what to do next. * The commit detail page keeps the file changes table inside its card. ### Highlights #### Also in this release * Reanalyzing a commit from the interface now completes reliably and shows correct details. ### Important changes | What changed | What you will notice | What you can do | | ---------------------------------------------------------------------------------------- | --------------------------------------------------------------------------- | ------------------------------------------------------------------------------ | | Complexity and impact calculations now recognize renamed and moved files more precisely. | Complexity and impact scores for affected commits may be lower than before. | Compare periods inside the app. All periods use the same, updated calculation. | ### Fixes * Reanalyzing a commit now consistently displays its details. Navigara now connects to Azure DevOps, and architecture analysis becomes more flexible and more accurate. ### Highlights #### Azure DevOps support You can now connect Azure DevOps repositories to Navigara. Sign in with a personal access token or Microsoft Entra ID. Pull requests, reviewers, and approvals sync the same way they do for GitHub and GitLab. #### Flexible architecture analysis You can now choose which repositories architecture analysis covers: all of them, or a specific selection. Coverage also improved, so more of your codebase is captured under the right feature area. #### Also in this release * Signing in with Google now works reliably when your organization uses a custom frontend address. * Work attribution across shared directories and files touched by multiple features is now more accurate, reducing miscategorized activity. ### Important changes | What changed | What you will notice | What you can do | | -------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------- | | Performance scores no longer count merge commits, which previously duplicated the scoring of the underlying commits. | Past and present performance scores may be lower than before, reflecting each developer's individual commits more accurately. | Compare periods inside the app — all periods now use the same calculation. | ### Fixes * Browser tabs left open across a deployment now reload automatically instead of showing repeated errors. * The developer breadcrumb now appears when navigating from a developer's page to one of their commits. ### Fixes * Repository pages now show all developers who have contributed, including developers first seen on another repository. * The developer list on a repository page now matches the performance totals shown above it, and uses the same table experience as the team page, including team, seniority, and role filters and column visibility controls. ### Fixes * Improved scheduling so analysis keeps processing smoothly, and other work like summaries and metrics keeps moving during heavy load. * Polished several display details across the app, including chart controls, filters, and labels on the Teams page and elsewhere, for a cleaner and more consistent look in both light and dark themes. ### Highlights #### Sign in with Microsoft You can now sign in to Navigara with your Microsoft account. This includes work, school, and personal accounts. #### Feature contributions chart The Features page now includes a chart. It shows developer contributions to each feature over time. #### Also in this release * The organization switcher now supports search and pagination. This makes it faster to find and switch between organizations. * The Features page now shows which features depend on each feature. This replaces the previous interface list. ### Fixes * Repository list pagination now uses the correct total count. Page numbers and navigation are accurate. * The organization role picker now shows each member's actual role. ### Highlights #### Custom AI model connections Navigara now supports OpenAI-compatible AI model endpoints, in addition to the default provider. This lets you connect the model that fits your setup. #### Role filter on the average performance chart You can now filter the average member performance chart by role. This makes it easier to compare like with like. #### Smarter developer matching Navigara now recognizes when the same developer commits using different email addresses. It keeps them as one developer profile, so activity and performance stay in one place. #### Also in this release * The Features area moved after Objectives in the sidebar for a more logical flow. ### Important changes | What changed | What you will notice | What you can do | | --------------------------------------------------------------------------------------- | ------------------------------------------------------------- | ------------------------------------------------------------------------- | | The impact score calculation for commits now focuses on code complexity and engagement. | Impact scores may shift slightly compared to earlier periods. | Compare periods inside the app. All periods now use the same calculation. | ### Fixes * Root cause detection in commit analysis points to the originating commit more consistently. * Organizations with matching names automatically get a unique address. * Setup waits for your provider installation to finish before moving to the next onboarding step. * We strengthened the security of the platform. ### Highlights #### Objective detail pages Every objective now has its own detail page. It shows a stacked area chart of grow, maintenance, and waste effort over time, plus breakdowns by developer and by project. Objectives with no recorded work yet show a clear "work hasn't started" state instead of an empty chart. You can also open the linked Linear issue directly from the page. #### Features list Organizations that turn on architecture analysis in settings now get a Features page. It lists detected architectural features, with expandable details for each feature's dependencies and entry points. #### Also in this release * The objectives chart now has an Absolute / Percent toggle, so you can view effort as raw amounts or as a share of the total. * Admins can now invite multiple people by email at once from the organization panel. * Team average performance charts gained a comparison mode toggle. ### Fixes * Accepting an organization invitation now only auto-completes when the logged-in account matches the invited email. * Accepting an invitation now always switches your active session to the invited organization. * The team average performance graph animation now displays correctly. ### Highlights #### Bitbucket Cloud support You can now connect Bitbucket Cloud repositories alongside GitHub and GitLab. Navigara discovers your Bitbucket repositories, analyzes commits, and tracks pull requests the same way it does for other providers. #### See how work connects to your objectives Commits can now be linked to the Issue, sub-objective, and objective they belong to. This is based on your issue tracker hierarchy. It works whether you connected your repositories or your issue tracker first. #### Redesigned objectives page The objectives page has a cleaner chart and a performance column with an at-a-glance score. Objectives are now ordered by target date. Hovering a row highlights it on the chart and vice versa. You can filter to objectives active in your selected time range. #### Also in this release * Organizations can turn AI-detection columns on or off for their Developers, Repositories, and Teams tables. * Repository settings now include a "Check for new commits" option to catch up any commits that were missed. ### Fixes * Moving a repository's analysis start date to an earlier date now analyzes the commits in the newly covered range. * Reanalyzing a repository after a temporary processing issue no longer skips previously skipped commits. * The app no longer shows a stale-session error after a period of inactivity. * Background summary and metric updates now skip periods that are already finalized. Navigara v0.9.0 brings a new way to see how AI tools contribute to your codebase, more flexible work-category reporting, and a more organized way to structure objectives. ### Highlights #### AI-augmented commit detection Navigara now automatically identifies commits created with the help of AI coding tools. It uses signals like co-author information, commit patterns, and branch names. You will see an "AI %" badge next to performance scores on the developers, repositories, and teams pages, so you can track how much of your team's work is AI-assisted. #### Flexible work-category reporting You can now choose how work is grouped across dashboards, charts, and reports. Pick the classic Grow / Maintenance / Waste view, or a simplified Grow / KTLO view that combines maintenance and waste into one category. Switch anytime from Settings. #### Reorganized objectives Objectives can now be folded to show or hide their child projects. This makes it easier to scan a long list of objectives and drill into the ones you care about. Objective detail pages also show more accurate child status counts. #### Also in this release * Clicking a developer's icon now takes you straight to their developer profile. * The developers page gained filters for role, team, and seniority. * Developer avatars now use their connected GitHub profile picture where available. * The onboarding experience has a refreshed layout and icons. ### Important changes | What changed | What you will notice | What you can do | | ------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------- | | Legacy quality, velocity, and performance scores have been retired in favor of the Grow / Maintenance / Waste (or Grow / KTLO) model. | These older score types no longer appear on dashboards or reports. | Use the Grow / Maintenance / Waste (or Grow / KTLO) categories for the same insights going forward. | | Minimum password length for new and changed passwords is now 8 characters. | Signing up, resetting, or changing a password now requires at least 8 characters. | Choose a password of 8 characters or more. | ### Fixes * The role selector on the team performance graph now works. * Selected time range and bucket size are preserved when navigating between developer and team detail views. * Requests that hit a temporary rate limit now retry automatically. * Objectives show accurate child status counts and improved contrast for status themes. * Repository links in the commits view now take you to the correct repository page. * We strengthened the security of account authentication and password handling. ### Highlights #### Objectives from your issue tracker Navigara can now automatically create and update objectives from your issue tracker's initiatives. Objectives are matched using the initiative hierarchy. Branch names serve as a fallback when an issue reference is not available, so more of your delivery work is captured without manual setup. #### More deployment flexibility for self-hosted teams Organizations running Navigara on their own infrastructure can now run analysis independently from the rest of the platform. They can connect it over a dedicated network endpoint and turn on a dedicated analysis setting per organization. This gives self-hosted teams more control over how and where analysis runs. #### Move from self-hosted to cloud Teams running Navigara on their own infrastructure can now migrate their data to the Navigara cloud using a new migration tool. #### Also in this release * Performance charts on the developer and repository pages load more efficiently. ### Fixes * The developers page now loads more efficiently, with fewer unnecessary requests. * Repository sync now reliably detects updated pull requests. * Dashboard sections recover gracefully if an error occurs, without affecting the rest of the page. * Analysis is more stable for repositories that contain non-standard text encoding. * We strengthened the security of authentication and internal communications. ### Fixes * The performance deviation percentage on developer and repository charts now uses the same benchmark baseline as the chart line, so the percentage and the chart always agree. * Open tabs refresh automatically after a new deployment, so you can keep taking actions without interruption. ### Highlights #### Guided onboarding New organizations now go through a guided setup. Tell us about your organization, connect your code source, choose the repositories to analyze, and watch Navigara analyze them in real time. You can navigate between steps using the page URL, and your progress is saved if you refresh. #### Sign in and connect with GitLab You can now sign in to Navigara with GitLab, alongside Google and GitHub. Organizations can also connect GitLab during onboarding or from Settings to discover and analyze repositories across their GitLab groups. #### Linear workspace integration Connect your Linear workspace from Settings to bring initiatives, projects, and issues into Navigara. Commits are automatically linked to the Linear issues they reference, and objectives are created and kept in sync from your Linear initiatives. #### Also in this release * Repository analysis now includes pull requests and merge requests from GitHub and GitLab, linked to the commits that merged them. * The developers and objectives pages now support keyboard navigation and are easier to use with screen readers. ### Fixes * Pagination controls across list pages now render correctly in both light and dark mode. * Newly connected repositories now start with the correct default branch. * We strengthened the security of organization membership, invitations, and data queries across the platform. ### Fixes * Invitation links now show the right sign-in or sign-up form based on whether you already have an account. * Analysis automatically recovers if a connection is interrupted partway through, without losing progress. ### Highlights #### MCP server for AI assistants Navigara now offers an MCP (Model Context Protocol) server. AI assistants such as Claude Desktop and Cursor can connect directly using your API key. Assistants can list your teams and pull AI-generated commit summaries and performance scores for a team without leaving the chat. #### Faster developers list The developers list now loads faster. Sorting and pagination are now handled server-side. ### Important changes | What changed | What you will notice | What you can do | | ------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- | | Developer and team metrics now group activity by developer identity instead of email address. | Counts and charts for developers with multiple linked email addresses may shift slightly. | Review team and developer pages. Merged developer identities are grouped consistently everywhere. | | The dashboard "Top 20% Sum" widget now calculates the top-performer share as a portion of total performance. | This value can now be lower than total performance. | Use the widget to compare top-developer concentration against total output. | ### Fixes * Invitation links now open for people who have not signed in yet. * Team pages now show the Repositories section and the Developer Performance chart. * The analysis status no longer shows an error badge for a run that a newer, successful run has already replaced. * Analysis now skips auto-generated helper files from framework tooling, keeping developer metrics focused on real work. ### Important changes | What changed | What you will notice | What you can do | | -------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------- | | Performance score calculation (growth, maintenance, and cleanup values) has been updated for report summaries. | Performance scores in your Reports may change. The performance badge now appears in more places. | Regenerate existing reports to see the updated scores. No action is needed for new reports. | ### Fixes * Excluding or including a commit now updates repository metrics right away. Excluded work no longer appears in graphs and reports. * Repository analysis details, such as author and cost information, are preserved when a later analysis attempt does not complete. ### Fixes * Analysis scheduling now skips repositories you have stopped. * Analysis scheduling only re-processes repositories with new activity, instead of repeating completed work. Navigara now processes only new activity during daily repository syncs, keeping your data current with less delay. ### Fixes * Daily repository syncs now process only new commits since the last analysis, so your data stays up to date faster. * Large repositories now have more time to complete analysis, improving reliability for repositories with a high volume of history. ### Highlights #### API tokens for programmatic access You can now create and manage Navigara API tokens directly from Settings. Generate a token, copy its key once at creation time, and revoke it later when it is no longer needed. #### Developer avatars Developers and teams now show profile pictures pulled from GitHub or GitLab. Clean initials appear as a fallback when no picture is available. #### Faster, more flexible metrics Performance metrics are now precomputed and stored in a query-ready form. Dashboards and reports load faster and stay consistent as team membership and tags change over time. #### Also in this release * Commits can now be sorted by performance on the commits page. * The performance chart legend shows a tooltip explaining each series. * The admin panel shows analysis connection status, so operators can see health at a glance. * Developer detail pages paginate commits for smoother browsing on active developers. * Light theme styling has been refined across components. * The time picker better recognizes preset ranges and remembers your selection across page refreshes. * You can now filter developers by when they joined and by probation status. ### Fixes * Commits appear in the report sheet view. * Trend calculations in the dashboard summary section are accurate. * Minified files are skipped during commit analysis, avoiding noise in results. * The zero-day index only applies to developers, as intended. * Team assignment reflects current team membership consistently. * Developers with missing email data are handled in commit queries. * Session handling has been made more resilient, reducing unexpected sign-outs. ### Fixes * You can now add a personal access token for a GitHub Enterprise instance. If adding the token fails, you now see a clear message instead of the dialog closing silently. ### Highlights #### GitHub Enterprise support for tokens Navigara now validates access tokens against GitHub Enterprise instances, not just github.com. If your organization runs its own GitHub Enterprise deployment, you can add and use tokens for it directly. #### Also in this release * The Add token dialog now shows a clear, specific message when a token cannot be validated. ### Important changes | What changed | What you will notice | What you can do | | ----------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------- | ------------------------------------------------------------------------- | | The newcomers table on the developer dashboard uses a consistent calculation for performance figures. | Numbers for newcomers on the dashboard may look slightly different than before. | Compare periods inside the app. All periods now use the same calculation. | ### Highlights #### Simplified connections settings The Tokens page is now part of Connections. Each provider (GitHub, GitLab, Bitbucket) shows as a collapsible card with its token count and an expandable token list. You manage every connection from one place. #### Repositories contribution on team detail Team detail pages now include a repositories contribution section. It shows which repositories a team's developers are actively contributing to. #### Also in this release * Filters show a clearer selected state and support multiple active filters at once. * Line charts show a loading skeleton while data is being fetched. * Your selected time range and bucket size are preserved as you navigate between pages. * Git tokens let you specify the provider explicitly, improving support for self-hosted GitHub Enterprise, GitLab, and Bitbucket instances. ### Important changes | What changed | What you will notice | What you can do | | -------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------- | | The reach factor in performance scoring now counts unique external files that depend on a change, excluding references within the same file. | Performance scores for some commits, especially in files with many internal references, may shift. | Compare periods inside the app. All periods use the same updated calculation. | ### Fixes * Team charts load team members directly, so team performance data displays reliably. * Metadata updates handle empty values, keeping repository and team metadata consistent. Navigara v0.6.0 introduces Teams, a new way to group developers and track their performance together, along with a redesigned developer detail page and a smoother reporting experience. ### Highlights #### Teams You can now group developers into Teams and view their combined performance over time. Each team gets its own detail page with a performance chart, member search, and an AI-generated summary of the team's work. You can create, edit, and configure teams from Organization Settings. #### Developer detail redesign The developer detail page now shows a repository-by-repository breakdown of performance. This makes it easier to see where a developer's work is happening. Charts across the product now share one consistent tooltip style, so you can compare grow, maintenance, and waste values at a glance. #### Also in this release * The projects list has a refreshed layout. * Reports now animate smoothly when opening. * Organization Settings includes a new option to refresh your data on demand. ### Fixes * The developers table on the dashboard updates when you change the time range. * The performance graph on the team detail page displays reliably. * Charts and filters are easier to read in light theme. * The server shuts down cleanly during restarts, avoiding delayed availability. ### Highlights #### Redesigned dashboard, repository, and developer views The dashboard, repository detail page, and repositories list page have a new look and feel, with clearer layouts. The repositories list also has a new performance chart. Developer list tables on the dashboard are redesigned for easier scanning, and graph line tooltips are now clearer and easier to read. #### Also in this release * Analytics queries now support an industry-standard dimensions option for more flexible reporting. ### Fixes * Developer avatar initials now display when a name contains non-letter characters. * Commit history for developers now includes all of their associated email addresses. Small workflow improvements to developer reports, plus two connection fixes. ### Highlights #### Faster navigation to developer detail Click a point on a developer's line graph, or a time period on the developer detail page, to jump straight to the matching report. You can also sort commits inside the report pop-up window. #### Also in this release * Cleaned up spacing in the report pop-up window and on pages without a stat card. ### Fixes * Developers who commit using GitHub's private "noreply" email address are now matched to their existing account. * Repository sync with a GitLab on-premises server now completes when the server URL is entered without a protocol prefix. ### Fixes * The retry failed button in the work queue now retries only the failed items. You can recover from errors without rescanning everything else. ### Highlights #### Connect repositories with a GitHub App You can now connect your GitHub organization using a GitHub App instead of managing personal access tokens. This also improves developer matching by recognizing multiple email addresses, including no-reply and alias addresses, for the same developer. #### Redesigned developer list The developers list has a refreshed look. It includes a new performance graph, clearer table columns, simplified filters, and a new pagination control with a page size selector. #### Also in this release * You can now edit a developer's joining date, set a probation period, and filter the developer list by probation status. * The performance graph and its deviation stat card have a cleaner, easier-to-read design. ### Important changes | What changed | What you will notice | What you can do | | ------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------- | | Performance metrics are now expressed on a 0-100 scale. | Metric values across the app will look different from before, even though they reflect the same underlying activity. | Compare periods inside the app going forward. All periods use the same 0-100 scale. | ### Fixes * Cloning private repositories connected through a GitHub App now works reliably. * Charts display dates consistently regardless of your time zone. * Week numbers on charts that start on Sunday now display correctly. * Repository data access is now scoped to the correct organization. ### Fixes * The repository benchmark selector no longer shows an option for a day with no activity. * Performance summaries generate only for fully completed periods. This gives you more consistent results. ### Highlights #### Zero-day index view Charts now offer a Zero-day index visualization mode alongside the Organization average. It shows upper and lower bands around the benchmark average, so you can see how performance spreads over time. The legend and tooltip show performance, average, and spread. #### Custom benchmarks in charts You can now select a custom benchmark from the chart dropdown menu, in addition to Organization average and Zero-day index. The average performance deviation card updates its name to match your selected benchmark. #### Also in this release * The Zero-day index option is now available directly from the repositories dropdown menu. ### Fixes * Repository sync now completes reliably, even when some items previously required a retry. ### Highlights #### Copy your organization ID The general settings page now shows your organization ID. Use the one-click copy button to share it quickly when needed. ### Highlights #### Filter dashboard metrics by developer group You can now filter dashboard metrics by a group of developers at once. This makes it easy to compare a selected cohort against team or organization averages. ### Highlights #### Improved commit analysis quality We upgraded the underlying model that powers commit analysis. This improves the quality of analysis results. ### Highlights #### Faster commit history for large repositories Pages that list commits and developer activity now load significantly faster for organizations with large histories. This holds even with tens of thousands of commits. #### Faster analysis processing Behind-the-scenes processing for developer summaries is now much lighter on system resources. This keeps analysis running smoothly as organizations grow. ### Important changes | What changed | What you will notice | What you can do | | ------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------- | | Commit analysis now more thoroughly excludes generated and bundled build files (for example, minified JavaScript output) from complexity scoring. | Developer activity and complexity scores may shift for repositories that commit build output, better reflecting original work. | No action needed. The improved detection applies automatically going forward. | ### Fixes * Large result sets on the commits list now keep filtering and pagination consistent across pages. ### Fixes * Commit detail pages now load reliably in repositories with a large commit history. * When you merge or split a developer's email addresses, their commit history, contribution graph, and metrics update automatically to match. ### Fixes * The developer page now updates after you type a custom date into the time filter. ### Highlights #### Simplified dashboard navigation Dashboard pages no longer show a back-arrow control. Use your browser's back button or breadcrumbs to move around. ### Fixes * The sidebar toggle icon now collapses and expands the sidebar. ### Fixes * The navigation sidebar now collapses and expands smoothly, and the toolbar stays aligned with it. Navigara now gives you more control over which commits count toward your metrics, and refines how developer performance is measured against the organization average. ### Highlights #### Exclude commits from metrics You can now exclude individual commits from performance metrics, with a reason you choose. Excluded commits are marked on the commit page and are left out of all metrics calculations. #### Also in this release * Reanalyzing a commit now uses the improved analysis process, giving you more consistent results. ### Important changes | What changed | What you will notice | What you can do | | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- | | Developer and repository performance deviation is now calculated as the difference from the average performance per active developer, instead of an average of daily averages. | Deviation percentages on developer and repository pages can shift slightly from what you saw before. | Compare periods inside the app going forward — all periods now use the same calculation. | ### Fixes * Repositories pages linked directly with a time range in the URL now load and filter correctly. * Repositories hosted on GitLab Enterprise now detect the default branch reliably, even when it is not included in the initial project listing. ### Fixes * Summary reports now filter correctly by schedule type, scope, and period. * The file list dropdown in commit details now responds correctly when you select an item. Organization owners now have more control over their team, and repository discovery is clearer. ### Highlights #### Team member management Organization owners and admins can change a member's role, remove a member, or cancel a pending invitation. Each action has a confirmation step to prevent accidental changes. The owner role is shown as a fixed badge. You can no longer remove yourself or change your own role by accident. #### Also in this release * The developers table shows email addresses in a tooltip when you hover over a developer's name, keeping the table itself cleaner. * Repository discovery shows a loading indicator while Navigara searches for repositories to add. ### Important changes | What changed | What you will notice | What you can do | | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- | | Organization invitations and role settings no longer offer an "Admin" organization role. Only Owner, Member, and Viewer are available. The UI labels "Platform role" (system-wide) separately from "Organization role" (within an organization). | Existing members keep their current role. New invitations only offer Owner, Member, or Viewer. | Review your organization's member roles in team settings if you relied on the previous Admin option. | ### Fixes * Repositories with no commits in the selected period show a clear "No commits" status. * Clicking the dependency arrow in the file changes table keeps your session active. * Period summaries update in place and show when they were last generated. ### Highlights #### Configurable periodic summaries Navigara now generates periodic summaries automatically. You get a regular, up-to-date view of developer and repository performance without asking for one. #### Redesigned performance graphs Repository and developer performance graphs now let you switch between relative and absolute views. You can compare against the organization average from a dropdown menu. #### Visibility into skipped files and commits Analysis now shows which files and commits were filtered out, for example lockfiles or generated code. A clear explanation shows what is included in your metrics. #### Also in this release * A quick-access arrow on the repository developers list takes you straight to each developer's page. ### Important changes | What changed | What you will notice | What you can do | | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------- | ------------------------------------------------------------------------- | | The performance deviation stat now compares a repository's total output (growth, maintenance, and waste combined) against the organization's monthly average for the same period. | Deviation values on repository and developer pages can shift compared to before. | Compare periods inside the app. All periods now use the same calculation. | ### Fixes * The developers page loads for organizations with more than 1,000 developers. * You can assign a developer to a team in organizations with more than 1,000 developers. * Seniority level displays for developers. * Benchmark charts aggregate data based on the selected time bucket. ### Highlights #### Custom benchmarks You can now save groups of developers or repositories to compare against. Choose average, median, or another percentile for how the group is aggregated, so comparisons match the way your team works. ### Fixes * Newly connected repositories now show complete commit metrics from the start of analysis. This release brings cleaner performance charts, more reliable repository views, and new developer tracking fields. ### Highlights #### Flexible time aggregation for commit activity The Commits view now lets you group commit activity by day, week, or month. Zoom in for recent detail or zoom out for a longer trend. #### Probation tracking for developers You can now record a developer's joining date and end of probation date. This makes it easier to track ramp-up periods alongside performance history. #### Also in this release * Developer day detail pages now show the developer's name in the breadcrumb. * The global time picker now accepts month ranges that span into the next year, for example "Dec 2025 - Jan 2026". ### Fixes * Repository pages keep open dropdown menus open while a repository analysis is in progress. * Performance and dashboard charts show date labels clearly, without overlapping text. * Selecting a seniority level on the developer filters no longer clears the selected team, and vice versa. ### Highlights #### Seniority levels for developers You can now assign a seniority level to each developer. Choose Junior, Medior, Senior, or a custom level. Use the new seniority filter to view and compare developers by level. Navigara now gives clearer summaries of your team's activity, makes token expiration easy to track, and adds a more flexible time picker. ### Highlights #### Clearer, more factual period summaries Period summaries describe what happened in plain, factual language. Commit and pull request references in a summary are clickable links, and key terms are highlighted for faster scanning. #### Redesigned time picker The time picker supports typing values directly and selecting custom ranges, with a fixed default time. This makes it faster to pick the exact period you want to view. #### Refreshed developer page The developer page has a cleaner, more consistent layout. #### Also in this release * API tokens on the tokens settings page show their expiration date, with clear badges for tokens that are expired or expiring soon. * Team and project charts use improved metric colors for better readability. ### Fixes * The invitation login page displays correctly. * Bucket size selection in team and project charts applies correctly. * Token expiration dates from GitHub are parsed correctly regardless of timezone format. ### Highlights #### PHP analysis Navigara now analyzes PHP repositories with the same depth as other supported languages. This includes accurate symbol detection and reference finding across your PHP codebase. #### Also in this release * List pages across Navigara (developers, teams, projects, repositories) now consistently apply your selected time range. ### Important changes | What changed | What you will notice | What you can do | | -------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------- | | The developers table now includes AI-assisted waste time in its totals, alongside growth and maintenance work. | Totals on the developers table may be higher than before for periods with AI-assisted work. | Compare periods inside the app. All periods now use the same calculation. | ### Fixes * Metrics now stay consistent when the same commit affects multiple repositories. * The time period selector now works after refreshing the page. Navigara is now available. This first release brings together AI-powered performance insights, flexible views of your Developers, Repositories, Teams, and Projects, and the account tools you need to get your Organization set up. ### Highlights #### AI-powered performance summaries Navigara generates AI-powered summaries for Repositories and Developers. Each summary highlights key strengths, concerns, and recommendations based on recent activity. You can regenerate a summary at any time as new work comes in. #### Teams and projects You can group Developers into Teams and Repositories into Projects. Each Team and Project gets its own detail view with a performance graph and a table of its members. This lets you track work at the level that matters to you. #### Commit knowledge graph Commit detail pages include an interactive graph. It shows how a commit's changes connect to the rest of your codebase. This makes it easier to understand the scope and impact of a change at a glance. #### Also in this release * A global time picker lets you choose custom date ranges and bucket sizes across dashboards. * Members can switch between Organizations they belong to directly from the sidebar. * Dashboards, Repositories, and Developer pages have clearer performance charts and benchmark visualizations. * Organization owners can invite members, manage Repository tokens, and reset passwords. * Repositories can be tagged and automatically grouped by Project. ### Fixes * Time range selections carry through to Team, Project, and Developer detail pages. * The Repository detail page shows the combined score for each developer. * Charts show only bars that reflect data for the selected range. * Developer emails are matched consistently regardless of capitalization, so contributions group correctly. # Alignment Source: https://docs.navigara.com/concepts/alignment How Navigara connects code changes to your roadmap and planning hierarchy. Alignment answers: **is the work connected to planned objectives?** Navigara links commits to your task management system (Linear, Jira, etc.) and traces each commit through your planning hierarchy: ``` Commit → Issue → Project → Initiative ``` ## How it works 1. **Issue extraction** — AI reads the commit message and code to find issue references (e.g. `ENG-123`, `#580`). 2. **Hierarchy resolution** — Each issue is resolved to its parent project and initiative(s) in your task tracker. 3. **Tagging** — The commit's metrics are tagged with the matched issue, project, and initiative so you can filter and aggregate at any level. ## What you see * **Aligned commits** are linked to at least one issue. You can drill down to see which project or initiative they support. * **Unaligned commits** have no issue reference. Some unaligned work is normal (quick fixes, tooling), but a consistently high ratio may indicate work happening outside the plan. Use alignment data to spot drift early — if a large share of effort is going to unplanned work, it's worth a conversation before the sprint ends. # Architecture Source: https://docs.navigara.com/concepts/architecture How Navigara maps your codebase into features, layers, and dependencies. Architecture maps your codebase into **named features** and shows how work distributes across them. It also powers the [architecture multiplier](/concepts/performance#architecture-multiplier) that adjusts performance scores based on structural complexity. ## Feature discovery When architecture analysis is enabled, Navigara runs a multi-phase AI agent per repository that: 1. **Explores** the codebase structure to discover distinct features (e.g. `auth`, `billing`, `notifications`). 2. **Organizes** each feature into vertical layers — frontend, backend, and data — with specific file paths. 3. **Maps dependencies** between features, showing which parts of the system are coupled. The agent produces a feature graph: nodes are features with known layers, edges are dependency relationships. This graph is used for both visualization and as input to the performance multiplier. ## Commit-to-feature matching Once features are discovered, every commit is matched to the feature(s) it touches based on the files it changes. This uses path-based scoring: | Match strategy | Confidence | | --------------------- | ---------- | | Exact path match | Highest | | Directory containment | High | | Filename affinity | Moderate | When a file belongs to multiple features (e.g. a shared utility), the match is weighted to avoid double-counting. ## Repository mesh When multiple repositories are connected to the same organization, their feature graphs are stitched into a **repository mesh** — a cross-repo dependency map. The mesh emerges from API contracts, shared libraries, and event flows detected by the architect agent. See [Performance > Repository mesh](/concepts/performance#repository-mesh) for how the mesh affects scoring. ## What you see All performance and alignment metrics can be **grouped by feature**, so you can answer questions like: * *Which features are getting the most investment?* * *Where is most of the bug-fix work concentrated?* * *Is the auth system seeing unplanned churn?* * *Which features have the highest structural complexity?* * *Where do cross-repository dependencies create leverage?* Architecture analysis is optional and can be enabled per repository. It's most useful for larger codebases where work naturally spans multiple distinct areas. # Performance Source: https://docs.navigara.com/concepts/performance How Navigara measures the volume and complexity of engineering work. Navigara measures engineering output per file change. Every modified source file in a merged commit produces three sub-scores — **growth**, **maintenance**, and **fixes** — each denominated in a common unit called **ETV** (Engineering Throughput Value) and reflecting both the type of work and the cognitive weight of the change. A commit touching five files contributes five independent measurements; contributor, team, and organization totals are sums over a time window. There is no single "Performance score." *Performance* in this document means the triple (growth, maintenance, fixes), computed identically at every level of aggregation. If you prefer a two-bucket view, see [KTLO mode](#ktlo-mode). ## The ETV unit All Navigara performance metrics are expressed in **ETV** (Engineering Throughput Value). Every file change contributes some amount of ETV to one of the three buckets — growth, maintenance, or fixes — and those amounts are summed across commits, contributors, teams, and repositories to produce every view in the product. ETV is additive within a work type: a contributor's growth ETV over a quarter is the sum of the growth ETV across every commit they merged in that quarter. It is deliberately not additive across work types — growth ETV and fix ETV reflect different kinds of output, so collapsing them into a single scalar would hide the signal the three-bucket model exists to surface. ETV is designed to be comparable over time for the same contributor, team, and repository. Cross-repository and cross-team comparisons are meaningful as trends, but raw ETV totals are not automatically normalized across repositories of very different size or language mix — see [The repository as context boundary](#the-repository-as-context-boundary) below. ## How a commit is scored Two things happen to every merged commit, in order. **Stage 1: AI analysis.** Navigara reads the commit message, the full diff, and the surrounding code context. For each changed file, the model classifies the type of work (growth, maintenance, fixes), identifies the changed symbols (functions, classes, endpoints), and, for bug fixes, traces the issue back to the originating commit, recording the original author and timestamp. Results are stored in a knowledge graph connecting commits, files, symbols, and issues. **Stage 2: Mechanical scoring.** Deterministic algorithms compute complexity and engagement over the same files. No LLM is involved at this stage. Scores are reproducible and consistent across runs. The AI determines *what kind of work* was done. The algorithms determine *how much*. File-level scores sum per work type, and those totals roll up into per-developer, per-team, per-repository, and per-organization views. ## Filtered files Navigara analyzes every source file modified in a commit, with a handful of non-authored categories filtered out before analysis begins: * **Generated code** — Protocol Buffer outputs (`.pb.go`, `_grpc.pb.go`, `.pb.ts`), GraphQL codegen (`.graphql.ts`), OpenAPI specs, and other machine-generated files (`*_generated.go`, `*.gen.go`, `zz_generated.*`). * **Dependency lockfiles** — `go.sum`, `package-lock.json`, `yarn.lock`, `pnpm-lock.yaml`, `Cargo.lock`, `Gemfile.lock`, and similar. * **Build artifacts** — `dist/`, `build/`, `.next/`, `vendor/`, `node_modules/`, and bundled outputs with content hashes (e.g. `main-YHGF2JUB.js`). * **Minified files** — detected by content heuristics when average line length exceeds 300 characters. * **Binary and media files** — images, fonts, PDFs, archives, compiled binaries. Filtered files are excluded from both AI analysis and mechanical scoring. If you see a commit with fewer scored files than total files changed, the difference is filtered files. The knowledge graph records which files were filtered and why. Teams with unusual generated-code conventions or build layouts can extend the filter list from organization settings to exclude additional paths. ## Supported languages Navigara provides full structural analysis — including fuzzy code skeletal matching, data flow analysis, and architectural outline extraction — for: C, C++, C#, Go, Java, JavaScript/TypeScript (including JSX/TSX), Kotlin, PHP, Python, Ruby, Rust, Scala, and Swift. For HTML, CSS, SQL, Terraform, shell, YAML, Markdown, and other declarative or configuration-heavy files, work-type classification still runs and the change still contributes to the score, but mechanical scoring has lower fidelity — context complexity is approximated from line-level signals rather than structural analysis. Need support for a language not listed here? [Contact us](mailto:support@navigara.com) and we'll look into adding it. ## Work types The AI classifies each file change based on what the diff actually does, not on commit message conventions. Prefixes are a hint, not a rule. | Type | What it captures | Conventional Commits hint | | --------------- | ------------------------------------------------------------------------------------------ | ------------------------------------------------------------------- | | **Growth** | New functionality, net-new capabilities | `feat` | | **Maintenance** | Upkeep, refactors, cleanup, performance, tests, dependency updates, docs, style, build, CI | `chore`, `refactor`, `perf`, `test`, `style`, `build`, `ci`, `docs` | | **Fixes** | Work that corrects previous output | `fix` | Classification is per file. A single commit can contain growth work in one file and a fix in another — each is scored independently. ## How the score is calculated Each file-level score starts from two deterministic inputs — **context complexity** and **engagement** — combined into a base score. Dampeners then adjust it, and for bug fixes a fix multiplier amplifies it. All adjustments apply before aggregation. **Context complexity** is computed per function scope over the added and modified lines, so the same number of changed lines can carry very different weight depending on what those lines do. The calculation works consistently across languages and paradigms — a React component blending JSX, JavaScript, and CSS-in-JS is scored on the same basis as a plain Go file. **Engagement** captures how much of the existing codebase the change had to reason about. Navigara derives this from two views: * **Inside the file.** For each modified function, Navigara identifies the existing lines the change actually interacts with — those that share identifiers with the changed lines, and those that flow into or out of calls on the changed lines via data flow analysis. Unrelated code in the same file is ignored. * **Across the repository.** Data flow doesn't stop at file boundaries. When a change alters a function's inputs, outputs, or externally-visible behavior, Navigara traces the affected values into callers and callees elsewhere in the repo — following the same reasoning the engineer had to do to make the change safely. Engagement reflects the surface area the developer actually had to understand, not a raw count of references. Engagement from heavily-reused utilities is bounded so that one-line edits to universal helpers don't dominate the score. File-level scores are then summed per work type, producing three numbers — growth, maintenance, and fixes — for any contributor, team, or repository over any time window. ### Decay and dampening factors Several factors reduce the base score when a change does not represent genuinely new cognitive work. All of them apply before aggregation. | Factor | What it does | | ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Similarity dampener** | Reduces credit when the change's *structure* closely matches patterns already in the codebase — mechanical refactors, boilerplate replication. Works on structural signatures of the change. | | **Blame decay** | Discounts changes that overwrite very recent work by the same author. The signal fades over a short business-day window, so revisiting older code is scored normally. | | **Copy decay** | Reduces credit when added *lines* are literally duplicated from elsewhere in the repo. Works on the text of the diff. | Thresholds and coefficients inside these factors — dampener sensitivities, engagement bounds, fix multiplier curves — are calibrated against a corpus of labeled commits and recalibrated periodically. They are the same across all customers; there is no per-customer model training. The formulas that consume them are fixed and auditable. The LLM is involved only in Stage 1 classification and bug-origin tracing, never in score computation. ### Fix multiplier When the AI identifies a file change as a bug fix, it traces the modified or deleted lines back to the commit that introduced the bug, recording the original author, timestamp, and churn history of the file. A **fix multiplier** then amplifies the score to reflect how much context a reader had to rebuild in order to make the fix safely. The multiplier grows when: * The bug lived in the codebase long enough that the fixer no longer has the original context fresh in mind. * The fix touches another author's code, raising context-transfer cost. * The affected area has been modified frequently since the bug was introduced, enlarging the risk surface. A trivial self-fix on code written the same day barely shifts the score. A fix in a high-churn area on code the fixer has never touched before is amplified substantially — the deeper the required context rebuild, the stronger the amplification. A healthy codebase typically shows high growth, moderate maintenance, and few fixes. A spike in fixes may signal quality issues worth investigating. ### Squash vs merge commits Teams land pull requests in different ways: merge commits preserve every commit on the feature branch; squash-merge collapses the branch into a single commit; rebase-and-merge replays commits onto the default branch. Performance is defined over whatever commits exist on the default branch after landing. The dampening factors are calibrated so that these paths converge. When a branch lands via merge commit, each constituent commit is scored individually and later commits are dampened where they overlap with earlier ones (similarity, blame decay, copy decay). When the same branch is squashed, the resulting commit carries the full scope in one shot without intermediate overlap to dampen. Totals come out close in either case. Performance is stable against your team's merge policy — you don't need to change how you merge to get meaningful numbers. ### Example A single commit touches four files: 1. **`api/auth/session.ts`** — adds a new `refreshSession()` function whose return value is consumed by multiple existing handlers across several files. Classified as **growth**. Context complexity is substantial (new control flow, async error paths). Engagement is high because the values produced by `refreshSession()` flow into call sites in other files — the engineer had to reason about each of those consumers to keep them compatible with the new behavior. Result: large growth contribution. 2. **`api/auth/login.ts`** — modifies the login handler to wire in `refreshSession()`. A small local edit, but the handler's modified return value continues to flow through downstream code in other files. Classified as **growth**. Moderate context complexity; engagement is lifted by the cross-file data flow rather than the size of the diff. Result: moderate growth contribution. 3. **`api/payments/charge.ts`** — fixes a null-check bug originally introduced by a different engineer many months earlier, in a file that has churned repeatedly since. Classified as **fix**. Small context complexity, but the fix multiplier amplifies it significantly: the bug is old, the fixer inherited the context, and the surrounding code has moved under them. Result: notable fix contribution. 4. **`.github/workflows/test.yml`** — bumps the Node version used in CI. Classified as **maintenance**. Minimal context complexity; no meaningful engagement. Result: small maintenance contribution. The commit's totals are the sums of these per-file scores by work type. ## The repository as context boundary Navigara scores changes within the context of their repository. Engagement is measured against the repo's other functions and call sites; context complexity is computed against local function scopes. Navigara does **not** perform cross-repository analysis — a change in repository A does not carry engagement weight from repository B, even if the two are related services. This is deliberate. The repository is the natural boundary of abstraction in most engineering organizations: it has a coherent build, review process, and ownership model. Cross-repo call graphs exist in practice but are rarely stable enough to use as a measurement substrate. Scores are therefore not automatically comparable across repositories of very different size or language mix. When comparing teams that work in different repos, compare trends within each team rather than raw totals across teams. ## Attribution ### Who gets credit Each commit is attributed to its **primary author** — the git author of the merged commit, after email alias resolution. Co-authors recorded in commit trailers are tracked in the knowledge graph but do not receive credit in the score. Contributors roll up to an organization via the repositories they commit to. A contributor active in multiple connected repositories within one organization is counted once, with their output summed across repos. **Bot and excluded contributors.** A default list covers common automation tools (`dependabot`, `renovate`, `github-actions`, and similar) and removes them from aggregated metrics. Organization admins can additionally flag any contributor as a bot — or mark them as excluded from rollups for other reasons — from the Contributors page. Flagged contributors remain visible in the knowledge graph for audit, but their commits do not contribute to aggregated performance metrics. ### When it counts Commits are attributed to the time window in which they were **merged to the default branch**, not when they were authored. In AI-native teams, work typically ships in days rather than weeks, so merge-date attribution closely tracks when the work actually happened. ## Supporting roles Senior engineers spend significant time on code review, architecture, mentoring, and technical decisions — work that rarely produces commits. Per-commit scoring does not capture these contributions directly, and aggregating commits to individuals will systematically underrate them. **Use team-level views as the primary lens.** A strong supporting engineer raises the output quality of everyone around them: fewer bugs (fewer fixes), cleaner architecture, faster onboarding. That impact shows up in the team's aggregate even when the individual's own commit-based score is low. Individual scores remain useful for understanding work distribution and spotting trends, but they should not be read as a complete performance picture when supporting roles are present. ## What Performance does not observe * **Only merged commits on connected repositories.** If a repository is not connected, its commits are not scored. A contributor who does most of their work in an unconnected repository will show a low score. * **Work that never lands as a commit.** Code review depth, incident response, planning, mentorship, pair-programming sessions that never produce a standalone commit, and any engineering contribution outside of merged code are not reflected. * **Author-rewriting tools.** Squash-merge policies that discard original authorship, or AI coding assistants that replace the human author, shift credit accordingly. Connect your AI coding tool integrations to retain the underlying authorship. ## KTLO mode By default, Navigara shows the full three-bucket breakdown: Growth / Maintenance / Fixes. If you prefer a simpler view, you can switch to **Growth / KTLO** mode in **Settings > General**. KTLO (Keep The Lights On) combines Maintenance and Fixes into a single category. This is useful when communicating with stakeholders outside of engineering — instead of explaining three categories, you get a clean split between new value (Growth) and everything else (KTLO). | Mode | Categories | Best for | | -------------------------------- | ---------- | ------------------------------------------------------------------ | | **Growth / Maintenance / Fixes** | 3 buckets | Engineering teams that want full visibility into where effort goes | | **Growth / KTLO** | 2 buckets | Executive reporting and cross-team communication | Switching metrics mode only changes how the data is displayed. The underlying analysis stays the same and you can switch back at any time without losing data. ## FAQ A large diff doesn't automatically mean a high score. If most of the added lines are structurally similar to existing code (the similarity dampener applies), literally duplicated from elsewhere (copy decay), or don't interact with much surrounding code (low engagement), the base score stays modest. Large mechanical additions — generated bindings, regenerated migrations, bulk renames — typically score low by design. A small change can carry significant weight when context complexity and engagement are both high. Rewriting one line inside a hot function that is called from dozens of places, or correcting an old bug in a high-churn area, both produce scores larger than their line count suggests. Yes — documentation and comment-only changes are classified as Maintenance and scored mechanically like other changes. They typically carry low context complexity and low engagement, so their contribution is small. No. A revert is classified based on intent — reverting a broken feature tends toward Fixes, reverting a merge-timing mistake tends toward Maintenance — and scored like any other change. The original commit's score is not retroactively removed. # Encrypted Git Tokens Source: https://docs.navigara.com/deployment/encrypted-git-tokens Encrypt Git tokens on your collector so Navigara stores them without ever being able to read them. ## Overview Running the [on-prem collector](/deployment/on-prem-collector) in hybrid mode, you can store a Git personal access token (PAT) that **Navigara can never read**. You encrypt the token on your own collector host; Navigara only ever stores and forwards the ciphertext. The collector holds the private key and decrypts each token in memory, only when it authenticates to the Git host — **the plaintext token and the private key never leave your network.** If a blob can't be decrypted (wrong key, tampering, or a paste error), the collector drops it and fails the task — it is never forwarded to the Git host. For the step-by-step setup (create the PAT, mount the key, paste the blob), see [On-Prem Collector → Provider Tokens, End-to-End Encrypted](/deployment/on-prem-collector#option-2-provider-tokens-end-to-end-encrypted-all-providers). This page is the CLI and rotation reference. ## Collector CLI The collector binary handles key generation and encryption — you already have it on the collector host. Tokens are read from **stdin**. ```bash theme={null} # Generate an X25519 keypair → private.pem (0600) + public.pem, and print the fingerprint. # Refuses to overwrite an existing private.pem. collector keygen --out /etc/navigara/keys # Encrypt a token → prints the navigara-enc-v1: blob to paste into the dashboard. echo -n 'ghp_yourtoken' | collector encrypt-token --public-key /etc/navigara/keys/public.pem # Verify a blob decrypts back to the original token. echo 'navigara-enc-v1:...' | collector decrypt-token --private-key /etc/navigara/keys/private.pem ``` Keep `private.pem` on the collector host — it is never shared. Then point the running collector at it for decryption: | Env var | Description | | ---------------------------- | ---------------------------------------------------------------------- | | `COLLECTOR_PRIVATE_KEY_PATH` | Path to a PEM private key. Comma-separate multiple files for rotation. | | `COLLECTOR_PRIVATE_KEY_PEM` | Inline PEM private key(s), as an alternative to the path. | ## Key rotation Both env vars accept **multiple keys**, and the collector picks the right one per blob. So you can roll a new key without downtime: generate it, add it to `COLLECTOR_PRIVATE_KEY_PATH` alongside the old one, re-encrypt and re-paste tokens at your own pace, then drop the old key once nothing uses it. # Full On-Premises Source: https://docs.navigara.com/deployment/full-on-premises Deploy all Navigara components within your infrastructure for complete data sovereignty. ## Overview Full on-premises deployment runs all Navigara components in your infrastructure. Source code, analysis results, and all metadata stay within your network. ## Architecture A full deployment consists of three infrastructure components: 1. **Linux VM** — runs the Navigara application (backend, frontend, collector) via Docker Compose 2. **Managed PostgreSQL** — stores all application data including vector embeddings (requires pgvector extension) 3. **LLM API endpoint** — Anthropic, OpenAI, or Google Vertex AI API for AI-powered commit analysis 4. **Navigara license key** — JWT issued by Navigara that unlocks analysis features (see [License Key](#license-key)) ```mermaid theme={null} graph TD Users([Users]) --> Caddy subgraph VM[Linux VM] Caddy[Caddy Reverse Proxy] Frontend[Frontend] Backend[Backend API] Collector[Collector\nGit, Issues, LLM] Caddy --> Frontend Caddy -->|/api/*| Backend Frontend --> Backend end Backend --> PostgreSQL[(PostgreSQL + pgvector)] Backend --> LLM[LLM API Endpoint] Collector --> Backend Collector --> LLM ``` ## Prerequisites ### Linux VM The VM runs all Navigara application containers via Docker Compose. **Operating system:** Ubuntu 24.04 LTS or Debian 13+ (other systemd-based Linux distributions may work but are not officially supported) **Required software:** * Docker Engine 24+ * Docker Compose v2+ ### Managed PostgreSQL A managed PostgreSQL instance with the pgvector extension enabled. All major cloud providers support this: * **AWS**: Amazon RDS for PostgreSQL with pgvector * **GCP**: Cloud SQL for PostgreSQL with pgvector * **Azure**: Azure Database for PostgreSQL with pgvector * **Self-managed**: PostgreSQL 18+ with pgvector extension installed **PostgreSQL version:** 18 (required for native UUIDv7 support via `uuidv7()`) **Required extension:** `pgvector` — vector similarity search for knowledge graph analysis ### License Key A full on-premises deployment requires a license key issued by Navigara. Contact your Navigara account representative with the domain you intend to host Navigara on (e.g. `navigara.yourcompany.com`) to obtain one. Set it as `LICENSE_KEY` in `secrets/backend.env`. Treat `LICENSE_KEY` as a secret. Store it alongside your other credentials (vault or secret manager) and do not commit it to source control. ### LLM API Endpoint Navigara requires an LLM API endpoint for AI-powered commit analysis. Supported providers: | Provider | Model | Notes | | -------------------- | ---------------------------- | ------------------------------------- | | **Anthropic** | Claude Sonnet / Claude Haiku | Recommended — best quality/cost ratio | | **Google Vertex AI** | Gemini 2.5 Flash | Good cost/performance ratio | | **OpenAI** | GPT-5.4 | Widely available | The endpoint must be reachable from the VM. For air-gapped environments, a locally hosted model with an OpenAI-compatible API (e.g. vLLM, Ollama) can be used — contact support for guidance. ```bash theme={null} LLM_PROVIDER=anthropic LLM_MODEL=claude-sonnet-4-20250514 LLM_API_KEY= LLM_API_URL=https://api.anthropic.com ``` `LLM_API_URL` is required. Claude Haiku (`claude-haiku-4-5-20251001`) costs less and runs faster. For Azure AI Foundry, internal API gateways, or other Anthropic-Messages-API-compatible endpoints, set `LLM_API_URL` to that endpoint. Do **not** include `/v1` in the URL — the SDK appends `/v1/messages` itself. Vertex AI uses Google authentication instead of a static API key. **1. Attach a workload identity** with the `Vertex AI User` role to the deployment host. **2. Set the following in the service file for each service that calls Vertex AI:** ```bash theme={null} LLM_PROVIDER=genai LLM_MODEL=gemini-2.5-flash GOOGLE_PROJECT= GOOGLE_LOCATION=global ``` **3. Use a JSON key only when no workload identity is available.** Create it with mode `0600` and mount it read-only into only the service that needs it. Set `GOOGLE_APPLICATION_CREDENTIALS` in that service file. ```bash theme={null} LLM_PROVIDER=openai LLM_MODEL=gpt-5.4 LLM_API_KEY= ``` Any model served behind an OpenAI-compatible API (e.g., vLLM, Ollama) can be used: ```bash theme={null} LLM_PROVIDER=openai LLM_MODEL= LLM_API_KEY= LLM_API_URL=http://:8000/v1 ``` Your setup may not need `LLM_API_KEY`. Contact support for guidance on model selection. ### Network Requirements The VM must have outbound access to the following services. Ensure your firewall rules allow these connections: | Service | Purpose | Example endpoints | | ------------------- | -------------------------------------- | ----------------------------------------------------------------- | | **Git provider** | Repository cloning and commit fetching | `github.com`, `gitlab.com`, or your self-hosted instance | | **Task management** | Alignment scoring via issue/task data | `api.linear.app`, `*.atlassian.net`, or your self-hosted instance | | **LLM API** | AI-powered commit analysis | `api.anthropic.com`, `api.openai.com`, or Vertex AI endpoints | If any of these services are unreachable, the corresponding Navigara features will not function. Git provider access is required for core functionality. ## Hardware Requirements Suitable for small to mid-size engineering teams. | Component | CPU | Memory | Disk | | -------------- | ------- | ------ | ---------- | | **Linux VM** | 16 vCPU | 16 GB | 500 GB SSD | | **PostgreSQL** | 16 vCPU | 32 GB | 500 GB SSD | Suitable for larger organizations with multiple teams and repositories. | Component | CPU | Memory | Disk | | -------------- | ------- | ------ | -------- | | **Linux VM** | 24 vCPU | 24 GB | 1 TB SSD | | **PostgreSQL** | 32 vCPU | 64 GB | 1 TB SSD | Suitable for enterprises with extensive Git history across many repositories. | Component | CPU | Memory | Disk | | -------------- | ------- | ------ | -------- | | **Linux VM** | 48 vCPU | 48 GB | 2 TB SSD | | **PostgreSQL** | 64 vCPU | 128 GB | 2 TB SSD | Knowledge graph data and vector embeddings drive the disk requirement. ## Installation ### 1. Prepare the VM Install Docker from Docker's own package repository. ```bash theme={null} sudo apt-get update sudo apt-get install -y ca-certificates curl sudo install -m 0755 -d /etc/apt/keyrings sudo curl -fsSL https://download.docker.com/linux/ubuntu/gpg -o /etc/apt/keyrings/docker.asc sudo chmod a+r /etc/apt/keyrings/docker.asc echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/ubuntu $(. /etc/os-release && echo "$VERSION_CODENAME") stable" \ | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null sudo apt-get update sudo apt-get install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin ``` ```bash theme={null} sudo apt-get update sudo apt-get install -y ca-certificates curl sudo install -m 0755 -d /etc/apt/keyrings sudo curl -fsSL https://download.docker.com/linux/debian/gpg -o /etc/apt/keyrings/docker.asc sudo chmod a+r /etc/apt/keyrings/docker.asc echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/debian $(. /etc/os-release && echo "$VERSION_CODENAME") stable" \ | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null sudo apt-get update sudo apt-get install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin ``` Then allow your user to reach the Docker socket, and confirm the install. Log out and back in for the group change to take effect. ```bash theme={null} sudo usermod -aG docker $USER docker compose version ``` Do not use the `get.docker.com` convenience script. Docker does not support it for production installs. ### 2. Verify the release Navigara publishes, for every release, a **signature**, a **software bill of materials (SBOM)**, and **build provenance** for each image. Verify them before you deploy. Install [cosign](https://docs.sigstore.dev/cosign/system_config/installation/), then verify each image at the digest you intend to run. Your account representative provides the digests for your release, and they are listed in [step 5](#5-prepare-environment-files). ```bash theme={null} NAVIGARA_VERSION=0.14.8 REGISTRY=europe-docker.pkg.dev/navigara-images/public cosign verify \ --certificate-identity-regexp "^https://github.com/navigaracom/vision/\.github/workflows/release\.yml@refs/tags/v" \ --certificate-oidc-issuer "https://token.actions.githubusercontent.com" \ "$REGISTRY/vision-be@sha256:b6a77526204301170cb89afa8f198f097ff2f03510c09a948b90424b1de17ce1" ``` A successful verification prints the signed claims. Repeat for `vision-collector` and `vision-fe`. Then read the provenance and the SBOM, which travel with the image: ```bash theme={null} docker buildx imagetools inspect "$REGISTRY/vision-be:$NAVIGARA_VERSION" \ --format '{{ json .Provenance }}' docker buildx imagetools inspect "$REGISTRY/vision-be:$NAVIGARA_VERSION" \ --format '{{ json .SBOM }}' ``` Feed the SPDX SBOM to your own vulnerability scanner if your policy requires it. If `cosign verify` reports `no signatures found` or `no matching signatures`, **stop**. Either the version you pinned predates image signing — install the current release instead — or the image is not the one Navigara published. Contact support before deploying it. ### 3. Configure the deployment Create the deployment directory structure and `docker-compose.yml`: ```bash theme={null} mkdir -p /opt/navigara/caddy && cd /opt/navigara ``` This deployment is hardened by default. Keep the `read_only`, `cap_drop`, `security_opt`, resource limit, and network settings as written. ```yaml theme={null} services: backend: image: ${BACKEND_IMAGE:?set BACKEND_IMAGE in .env to a digest-pinned reference} container_name: navigara-backend init: true env_file: - ./secrets/backend.env environment: DATABASE_MAX_CONNS: ${DATABASE_MAX_CONNS:-10} DATABASE_MIN_CONNS: ${DATABASE_MIN_CONNS:-2} GRPC_PORT: ${GRPC_PORT:-9090} HTTP_PORT: ${HTTP_PORT:-8080} LOG_LEVEL: ${LOG_LEVEL:-INFO} LLM_MAX_TOKENS: ${LLM_MAX_TOKENS:-8192} MIGRATIONS_PATH: ${MIGRATIONS_PATH:-db/migrations} FRONTEND_URL: https://${DOMAIN:?set DOMAIN in .env} PUBLIC_API_URL: https://${DOMAIN}/api # Uncomment for a Vertex AI service account key file # volumes: # - ./vertex-ai-key.json:/etc/navigara/vertex-ai-key.json:ro read_only: true tmpfs: - /tmp:mode=1777,size=512m cap_drop: - ALL security_opt: - "no-new-privileges:true" deploy: resources: limits: cpus: "${BACKEND_CPUS:-4.0}" memory: ${BACKEND_MEMORY:-4g} pids: 512 healthcheck: test: ["CMD", "bash", "-c", "exec 3<>/dev/tcp/127.0.0.1/${HTTP_PORT:-8080}"] interval: 15s timeout: 5s retries: 5 start_period: 60s restart: unless-stopped networks: navigara-edge: priority: 100 navigara-app: priority: 50 navigara-collector: priority: 10 collector: image: ${COLLECTOR_IMAGE:?set COLLECTOR_IMAGE in .env to a digest-pinned reference} container_name: navigara-collector init: true env_file: - ./secrets/collector.env environment: SERVER_ADDR: backend:${GRPC_PORT:-9090} COLLECTOR_ID: ${COLLECTOR_ID:-collector-1} MAX_WORKERS: ${COLLECTOR_MAX_WORKERS:-10} WORK_DIR: /tmp/git-analysis volumes: - collector-workdir:/tmp # Uncomment for a Vertex AI service account key file # - ./vertex-ai-key.json:/etc/navigara/vertex-ai-key.json:ro depends_on: backend: condition: service_started read_only: true cap_drop: - ALL security_opt: - "no-new-privileges:true" deploy: resources: limits: cpus: "${COLLECTOR_CPUS:-8.0}" memory: ${COLLECTOR_MEMORY:-8g} pids: 4096 restart: unless-stopped networks: navigara-collector: priority: 100 frontend: image: ${FRONTEND_IMAGE:?set FRONTEND_IMAGE in .env to a digest-pinned reference} container_name: navigara-frontend init: true environment: BACKEND_API_URL: ${BACKEND_API_URL:-http://backend:8080} NODE_ENV: ${NODE_ENV:-production} read_only: true tmpfs: - /app/.next/cache:mode=1777,size=256m - /tmp:mode=1777,size=64m cap_drop: - ALL security_opt: - "no-new-privileges:true" deploy: resources: limits: cpus: "${FRONTEND_CPUS:-2.0}" memory: ${FRONTEND_MEMORY:-1g} pids: 256 depends_on: - backend healthcheck: test: ["CMD", "wget", "--no-verbose", "--tries=1", "--spider", "http://127.0.0.1:3000"] interval: 15s timeout: 5s retries: 3 start_period: 15s restart: unless-stopped networks: navigara-edge: priority: 100 navigara-app: priority: 50 caddy: image: ${CADDY_IMAGE:?set CADDY_IMAGE in .env to a digest-pinned reference} container_name: navigara-caddy init: true environment: DOMAIN: ${DOMAIN:?set DOMAIN in .env} ports: - "80:80" - "443:443" - "443:443/udp" volumes: - ./caddy/Caddyfile:/etc/caddy/Caddyfile:ro - caddy-data:/data - caddy-config:/config read_only: true tmpfs: - /tmp:mode=1777,size=64m cap_drop: - ALL cap_add: - NET_BIND_SERVICE security_opt: - "no-new-privileges:true" deploy: resources: limits: cpus: "${CADDY_CPUS:-1.0}" memory: ${CADDY_MEMORY:-256m} pids: 128 depends_on: - frontend restart: unless-stopped networks: navigara-edge: priority: 100 volumes: collector-workdir: name: navigara-collector-workdir caddy-data: name: navigara-caddy-data caddy-config: name: navigara-caddy-config networks: navigara-edge: name: navigara-edge driver: bridge navigara-app: name: navigara-app driver: bridge internal: true navigara-collector: name: navigara-collector driver: bridge ``` The collector is attached to `navigara-collector` only, so it cannot reach Caddy or the frontend. A self-hosted database belongs on `navigara-app`. ### 4. Generate Root Private Key Generate an Ed25519 key pair for admin root access. You will use the private key to generate login links in [Product Setup](#9-product-setup). ```bash theme={null} PRIVKEY_PEM=$(openssl genpkey -algorithm Ed25519) PUBKEY=$(echo "$PRIVKEY_PEM" | openssl pkey -pubout -outform DER | tail -c 32 | base64) SEED=$(echo "$PRIVKEY_PEM" | openssl pkey -outform DER | tail -c 32 | base64) umask 077 printf -- "-----BEGIN PRIVATE KEY-----\n%s\n-----END PRIVATE KEY-----\n" "$SEED" > admin_key.pem chmod 0600 admin_key.pem echo "Public key (use below): $PUBKEY" echo "Private key saved to: admin_key.pem" ``` The `admin_key.pem` file is a root credential for your Navigara instance. Store it in a vault or password manager, and restrict access to named administrators. ### 5. Prepare Environment Files Use `.env` only for non-secret Compose settings. Use a separate `0600` file for each service. Do not mount a secret file in the frontend. | File | Service | Minimum values | | ----------------------- | -------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | | `.env` | Compose only | `NAVIGARA_VERSION`, `DOMAIN`, and optional image overrides | | `secrets/backend.env` | Backend only | `DATABASE_URL`, `LICENSE_KEY`, `ADMIN_PUBLIC_KEY`, `COLLECTOR_API_KEY`, `PAGINATION_TOKEN_SECRET`, and enabled authentication, email, or LLM values | | `secrets/collector.env` | Collector only | `COLLECTOR_API_KEY`, `LLM_PROVIDER`, `LLM_MODEL`, and the LLM credential or workload identity configuration | | No file | Frontend | No secrets. Compose provides only `BACKEND_API_URL` and `NODE_ENV`. | Create the public Compose file. Pin every image by digest. Verify each digest as described in [step 2](#2-verify-the-release) before you start the stack. ```bash theme={null} cat > .env <<'EOF' NAVIGARA_VERSION=0.14.8 DOMAIN=navigara.yourcompany.com BACKEND_IMAGE=europe-docker.pkg.dev/navigara-images/public/vision-be:0.14.8@sha256:75e395d9a3a8c893e5b99e90c9b26bf14c3366f4965bbebe6014980ba9fa575d COLLECTOR_IMAGE=europe-docker.pkg.dev/navigara-images/public/vision-collector:0.14.8@sha256:d28a213910ed1a1e477836ddfdff4f49400a529127e5df1901200b4f4b9cd1e3 FRONTEND_IMAGE=europe-docker.pkg.dev/navigara-images/public/vision-fe:0.14.8@sha256:d3d09213ec57cce3e705f428eb33928e9ca1407581562c185de2e59dd4a9f67b CADDY_IMAGE=docker.io/library/caddy:2.11.4-alpine@sha256:5f5c8640aae01df9654968d946d8f1a56c497f1dd5c5cda4cf95ab7c14d58648 # BACKEND_CPUS=4.0 # BACKEND_MEMORY=4g # COLLECTOR_CPUS=8.0 # COLLECTOR_MEMORY=8g # FRONTEND_CPUS=2.0 # FRONTEND_MEMORY=1g # CADDY_CPUS=1.0 # CADDY_MEMORY=256m EOF ``` These digests are for 0.14.6. Your account representative provides the digests for every release. The commented resource limits match the Small hardware tier — raise them when you move to a larger tier. Create the secret files from your secret manager. Set restrictive permissions before writing them. Do not put a literal token in a shell command or shell history. ```bash theme={null} install -d -m 0700 secrets install -m 0600 /dev/null secrets/backend.env install -m 0600 /dev/null secrets/collector.env ``` The backend file needs this minimum configuration. Add optional values only for enabled features. ```dotenv theme={null} DATABASE_URL=postgresql://navigara:***@:5432/navigara?sslmode=require LICENSE_KEY= ADMIN_PUBLIC_KEY= COLLECTOR_API_KEY= PAGINATION_TOKEN_SECRET= # LLM_PROVIDER=anthropic # LLM_MODEL=claude-sonnet-4-20250514 # LLM_API_KEY= # ENABLE_PASSWORD_AUTH=true # PASSWORD_HASH_PEPPER= # GOOGLE_CLIENT_ID= # GOOGLE_CLIENT_SECRET= # MICROSOFT_CLIENT_ID= # MICROSOFT_CLIENT_SECRET= # SMTP_HOST=smtp.your-provider.com # SMTP_USERNAME= # SMTP_PASSWORD= ``` With password auth you must also set `PASSWORD_HASH_PEPPER` to 32 bytes or more. The backend refuses to start without it, and you cannot rotate it. Generate `PAGINATION_TOKEN_SECRET` once with your secret manager and set it. Without it, the backend starts on a shared default value and only logs a warning, so your own checks must catch its absence. Use the same generated `COLLECTOR_API_KEY` value in `secrets/backend.env` and `secrets/collector.env`. The collector file contains only its connection and LLM configuration: ```dotenv theme={null} COLLECTOR_API_KEY= LLM_PROVIDER=anthropic LLM_MODEL=claude-sonnet-4-20250514 LLM_API_KEY= # COLLECTOR_PRIVATE_KEY_PATH=/etc/navigara/keys/private.pem ``` Prefer an attached workload identity for Vertex AI. Do not use a static service-account JSON key. If no workload identity is available, mount a `0600` key file read-only into only the service that requires it. At least one authentication method must be configured for users to log in to Navigara. Enable one or more of: password auth (`ENABLE_PASSWORD_AUTH=true`), Google OAuth (`GOOGLE_CLIENT_ID` + `GOOGLE_CLIENT_SECRET`), or Microsoft OAuth (`MICROSOFT_CLIENT_ID` + `MICROSOFT_CLIENT_SECRET`). Without at least one of these, only the root admin can access the instance via [Product Setup](#9-product-setup). **On 0.14.6 and earlier, configure OAuth.** The invitation page offers only a sign-in form. An invited user who has no account cannot create one, so OAuth is the only way in. Later releases accept password signup from the invitation link. #### Email (SMTP) Navigara sends transactional email over **SMTP** — password resets, organization invitations, and the workspace-ready welcome message. Use any provider: Amazon SES, SendGrid, Postmark, Mailgun, Google Workspace, or an internal relay. Set `SMTP_HOST`, `SMTP_USERNAME`, and `SMTP_PASSWORD`. `SMTP_PORT` defaults to `587` (STARTTLS) and `SMTP_FROM` defaults to `SMTP_USERNAME`. For an IP-allowlisted internal relay that needs no credentials, set `SMTP_HOST` and leave the username and password empty. Use `SMTP_TLS=ssl` with `SMTP_PORT=465` for providers that require implicit TLS. Email is optional. Without `SMTP_HOST`, Navigara runs normally but sends no email. Password resets and invitations are not delivered, so you need an authentication method that does not depend on email — OAuth/SSO, or sharing the invitation link directly. ### 6. Configure PostgreSQL Connect to your PostgreSQL instance as its administrative user and run the following. On a managed service that user is `postgres` on Cloud SQL, the master user on RDS, or your Azure administrator login. ```sql theme={null} CREATE DATABASE navigara; CREATE USER navigara WITH PASSWORD ''; \c navigara CREATE EXTENSION IF NOT EXISTS vector; GRANT CONNECT, CREATE, TEMPORARY ON DATABASE navigara TO navigara; GRANT CREATE, USAGE ON SCHEMA public TO navigara; GRANT SELECT, INSERT, UPDATE, DELETE, REFERENCES, TRIGGER, TRUNCATE ON ALL TABLES IN SCHEMA public TO navigara; GRANT SELECT, UPDATE, USAGE ON ALL SEQUENCES IN SCHEMA public TO navigara; ``` Then set `DATABASE_URL` in `secrets/backend.env` to use the `navigara` user: ```dotenv theme={null} DATABASE_URL=postgresql://navigara:@:5432/navigara?sslmode=require ``` Navigara runs database migrations automatically on startup — no manual schema setup is needed. ### 7. Configure Reverse Proxy (Caddy) Navigara ships with [Caddy](https://caddyserver.com) as the reverse proxy. Caddy terminates TLS, provisions and renews certificates through Let's Encrypt, and routes between the frontend, the backend API, and the gRPC services. Create the Caddyfile at `caddy/Caddyfile`. The site address comes from `DOMAIN` in your `.env`: ``` {$DOMAIN} { header { Strict-Transport-Security "max-age=31536000; includeSubDomains; preload" X-Frame-Options "SAMEORIGIN" X-Content-Type-Options "nosniff" X-XSS-Protection "1; mode=block" Referrer-Policy "strict-origin-when-cross-origin" } handle /api/metrics { respond 404 } handle /api/debug/* { respond 404 } handle_path /api/* { encode gzip header { Access-Control-Allow-Origin "https://{$DOMAIN}" Access-Control-Allow-Methods "GET, POST, PUT, DELETE, OPTIONS" Access-Control-Allow-Headers "Authorization, Content-Type, X-Api-Key" Access-Control-Max-Age "86400" } @options method OPTIONS respond @options 204 reverse_proxy backend:8080 } handle { encode gzip reverse_proxy frontend:3000 } log { output stdout format json } } ``` The `/api/metrics` and `/api/debug/*` routes are unauthenticated, so this Caddyfile returns 404 for both. Never expose them publicly. ### 8. Start Navigara ```bash theme={null} docker compose pull docker compose up -d ``` Verify all services are running: ```bash theme={null} docker compose ps ``` Confirm the containment controls took effect. Each application container must run as user `1001` and hold no Linux capabilities: ```bash theme={null} for c in navigara-backend navigara-collector navigara-frontend; do printf '%s uid=%s caps=%s\n' "$c" \ "$(docker exec "$c" id -u)" \ "$(docker exec "$c" grep -m1 CapEff /proc/self/status | awk '{print $2}')" done ``` Expect `uid=1001` and `caps=0000000000000000` for all three. Caddy runs with `CAP_NET_BIND_SERVICE` alone (`0000000000000400`), so it can bind ports 80 and 443. Only the reverse proxy should publish a host port: ```bash theme={null} docker ps --format '{{.Names}}\t{{.Ports}}' ``` ### 9. Product Setup Log in as root to create the first organization and invite users. Use the `admin_key.pem` you generated in [step 4](#4-generate-root-private-key). **Generate a Root Login** The Python script below signs a **one-time credential** and hands it to your browser from a local page. The credential expires **60 seconds** after it is signed and works only once. **Requirements:** PyJWT and cryptography, in a virtual environment. Ubuntu 24.04 and other modern distributions refuse `pip install` into the system Python. Debian and Ubuntu also need the `python3-venv` package. ```bash theme={null} python3 -m venv ~/.navigara-admin ~/.navigara-admin/bin/pip install PyJWT cryptography ``` Run the script below with `~/.navigara-admin/bin/python` in place of `python3`. ```python theme={null} #!/usr/bin/env python3 """Generate a one-time root login for Navigara (on-prem).""" import argparse, base64, http.server, secrets, threading, time, webbrowser import jwt from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PrivateKey from cryptography.hazmat.primitives import serialization parser = argparse.ArgumentParser() parser.add_argument("--key", required=True, help="Path to Ed25519 private key PEM file") parser.add_argument("--domain", required=True, help="Your Navigara domain (e.g. navigara.yourcompany.com)") args = parser.parse_args() with open(args.key) as f: lines = [l.strip() for l in f if not l.startswith("-----")] seed = base64.b64decode("".join(lines)) key = Ed25519PrivateKey.from_private_bytes(seed) pem = key.private_bytes(serialization.Encoding.PEM, serialization.PrivateFormat.PKCS8, serialization.NoEncryption()) host = args.domain.split(":")[0] now = int(time.time()) token = jwt.encode({ "jti": secrets.token_hex(16), "iss": "deployment-admin", "sub": "root", "aud": [host], "typ": "navigara.support.access.v1", "iat": now, "nbf": now, "exp": now + 60, }, pem, algorithm="EdDSA") target = f"https://{args.domain}/impersonate" page = f""" Signing in to Navigara """.encode() path = "/" + secrets.token_hex(16) served = threading.Event() class Handoff(http.server.BaseHTTPRequestHandler): def do_GET(self): if self.path != path or served.is_set(): self.send_error(404) return served.set() self.send_response(200) self.send_header("Content-Type", "text/html; charset=utf-8") self.send_header("Cache-Control", "no-store") self.send_header("Referrer-Policy", "no-referrer") self.send_header("Content-Length", str(len(page))) self.end_headers() self.wfile.write(page) def log_message(self, *a): pass server = http.server.HTTPServer(("127.0.0.1", 0), Handoff) url = f"http://127.0.0.1:{server.server_port}{path}" print(f"Signing in to {target}. If no browser opens, visit {url} within 60 seconds.") threading.Thread(target=server.serve_forever, daemon=True).start() webbrowser.open(url) if not served.wait(60): raise SystemExit("credential expired before the browser collected it") time.sleep(1) ``` Save this as `impersonate.py` and run it **on the workstation that holds the private key**, not on the server: ```bash theme={null} ~/.navigara-admin/bin/python impersonate.py --key admin_key.pem --domain navigara.yourcompany.com ``` Your browser opens on the platform administration page, signed in as the root admin. Create your first organization and invite users. Root belongs to no organization and has no dashboard of its own. Re-run the script whenever you need root access. Every run signs a new credential. A spent or expired credential cannot be reused. **Upgrading from 0.14.1 or earlier?** Replace any older copy of this script. An older copy fails with *"Sign-in links are no longer accepted"* or *"invalid or expired credential"*. A root session lasts 15 minutes, and signing in again ends the previous root session. ## Backup and Restore ### Database backup Back up your PostgreSQL database regularly using `pg_dump`: ```bash theme={null} pg_dump -h -U navigara -d navigara -Fc > navigara_backup_$(date +%Y%m%d).dump ``` ### Database restore ```bash theme={null} pg_restore -h -U navigara -d navigara --clean navigara_backup.dump ``` The database contains all application state. Ensure backups are stored securely and tested regularly. ## Monitoring and Health Checks The backend exposes a health check endpoint. The application containers publish no host port, so reach it through the proxy: | Endpoint | Description | | -------------------------------------- | ------------------------------------------------------------ | | `GET https:///api/health` | Application and database health (returns gRPC health status) | The backend and frontend containers also carry a Compose health check, so `docker compose ps` reports their status locally. Use these with your monitoring system (Prometheus, Datadog, etc.) to track service availability. Prometheus metrics stay on the container network. The proxy returns `404` for `/api/metrics`, because that route is unauthenticated. Scrape it from a container attached to `navigara-edge`, not from the host. ## Upgrades An upgrade is a change to the digests in your `.env`. Verify the new release before you run it, exactly as you did at install. 1. Back up the database. Migrations run automatically on startup. ```bash theme={null} pg_dump -h -U navigara -d navigara -Fc > navigara_pre_upgrade.dump ``` 2. Verify the new release, as in [step 2](#2-verify-the-release). ```bash theme={null} cosign verify \ --certificate-identity-regexp "^https://github.com/navigaracom/vision/\.github/workflows/release\.yml@refs/tags/v" \ --certificate-oidc-issuer "https://token.actions.githubusercontent.com" \ "europe-docker.pkg.dev/navigara-images/public/vision-be@sha256:" ``` 3. Update `NAVIGARA_VERSION` and all three image digests in `.env`, then restart. ```bash theme={null} cd /opt/navigara docker compose pull docker compose up -d ``` Your account representative provides the digests for each release. This page carries the digests for the current one. Change the version **and** all three Navigara digests together. A digest left on the previous release silently keeps that component on the old image, and mixed versions are not supported. ### Rolling back Keep the previous release's digests. A roll-back is the same procedure with the old values. Restore the database backup first if the newer release ran a migration — migrations do not run in reverse. ### Emergency security releases Navigara treats two classes of finding as emergencies. We ship a release for them on this clock, from the time we confirm the finding: | Class | Navigara publishes a release within | You should deploy within | | ---------------------------------------------------------------------------------------------------------------- | ----------------------------------- | --------------------------- | | A vulnerability under active exploitation, in Navigara or a component we ship | **48 hours** | **72 hours** of the release | | A credential compromise affecting Navigara-issued material — signing keys, license keys, or registry credentials | **24 hours** | **24 hours** of the release | We notify the technical contact on your account directly for both classes. For a credential compromise, also follow the instructions in the notice. It names what to rotate on your side and, if a signing key is involved, the new identity your `cosign verify` must expect. **Always verify the image during a key-compromise event.** All other findings follow the remediation targets in [Security best practices → Updates and patching](/security/best-practices#updates-and-patching). ## Troubleshooting | Issue | Solution | | ------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Analysis or collector features disabled | Verify `LICENSE_KEY` is set and matches your `DOMAIN`. Contact Navigara if your license has expired or needs to be reissued. | | Database connection refused | Verify `DATABASE_URL` and that the PostgreSQL instance allows connections from the VM's IP | | pgvector extension missing | Run `CREATE EXTENSION IF NOT EXISTS vector;` on the database as its administrative user | | LLM analysis failing | Verify `LLM_API_KEY` and that the VM can reach the LLM API endpoint | | High disk usage | Check knowledge graph data growth; consider scaling to a larger instance tier | | Migrations stuck | Clear the advisory locks against the database directly: `psql "$DATABASE_URL" -c "SELECT pg_advisory_unlock_all();"`, then restart the backend | | `cosign verify` reports `no signatures found` or `no matching signatures` | The version you pinned predates image signing, or the image is not the one Navigara published. Install the current release; if that also fails, contact support before deploying. | | A container restarts with a read-only filesystem error | The image needs a writable path this Compose file does not grant. Report it — do not remove `read_only`. Add a `tmpfs` entry for that path as a temporary measure. | | Backend or frontend unreachable on `127.0.0.1` | Expected. Only the reverse proxy publishes host ports; reach the application through your domain. | # On-Prem Collector Source: https://docs.navigara.com/deployment/on-prem-collector Deploy the Navigara collector inside your network while using the cloud SaaS platform. ## Overview The on-prem collector is a lightweight agent that runs within your network. It clones repositories, analyzes commits using an LLM, and streams only structured metadata (knowledge graphs, summaries, metrics) back to the Navigara cloud. **Source code never leaves your infrastructure.** ```mermaid theme={null} graph TD subgraph Your Network Collector[Navigara Collector] Git[Git Repositories] LLM[LLM API Endpoint] end subgraph Navigara Cloud API[Navigara API] Dashboard[Dashboard] end Collector -->|clone & fetch| Git Collector -->|commit analysis| LLM Collector -->|metadata only| API Dashboard -->|view results| API ``` The collector connects to the Navigara API over a persistent gRPC stream. It receives work assignments (which repos/commits to analyze), processes them locally, and sends back structured results. If the connection drops, it automatically reconnects with exponential backoff and replays any buffered results. ## Prerequisites * **Docker Engine 24+** and **Docker Compose v2+** on a Linux host (Ubuntu 24.04 LTS or Debian 13+ recommended) * **Network access** to your Git repositories (GitHub, GitLab, Bitbucket, or self-hosted) * **Outbound HTTPS** to the Navigara API (`app.navigara.com:443`) * **LLM API endpoint** — see [LLM Configuration](#llm-configuration) below ### Hardware Requirements | Scale | CPU | Memory | Disk | | ------------------------------ | ------- | ------ | ---------- | | **Small** (up to 500K commits) | 8 vCPU | 16 GB | 200 GB SSD | | **Medium** (up to 5M commits) | 16 vCPU | 32 GB | 500 GB SSD | | **Large** (up to 50M commits) | 32 vCPU | 64 GB | 1 TB SSD | Disk holds temporary Git clones. The collector caches cloned repositories to speed up later analyses. ## Git Provider Authentication The collector supports multiple authentication methods depending on your Git provider and security requirements. All credentials are configured in the Navigara dashboard and forwarded to the collector on demand over the encrypted gRPC stream — no static Git tokens are stored on the collector host. ### Option 1: Navigara GitHub App (Recommended for GitHub) Install the [Navigara GitHub App](https://github.com/apps/navigara) on your GitHub organization. **How it works:** 1. Install the Navigara GitHub App on your GitHub organization (or specific repositories) 2. Add the repositories in the Navigara dashboard 3. The backend generates scoped installation tokens on demand and sends them to the collector 4. Tokens are short-lived and automatically rotated **Advantages:** * No static tokens to manage or rotate * Fine-grained repository access (select specific repos during app installation) * Works with both GitHub.com and GitHub Enterprise ### Option 2: Provider Tokens, End-to-End Encrypted (All Providers) For any provider the GitHub App does not cover, use a personal access token, encrypted end to end so that **Navigara can never read it**. You generate a keypair on the collector host, encrypt the token locally, and paste the blob into the dashboard. Navigara stores and forwards that blob **verbatim**. There is no server-side key and no server-side decryption. The collector holds the private key and decrypts each token in memory, only when it authenticates to the Git host. **The plaintext token and the private key never leave your network.** This applies to the on-prem collector only. In a [full on-premises](/deployment/full-on-premises) deployment the whole platform runs inside your network, so paste the token directly and skip the encryption steps. Do these steps after [Installation](#installation). They use the digest-pinned `COLLECTOR_IMAGE` from the `.env` you create there. Load it into your shell first: ```bash theme={null} cd /opt/navigara && set -a && . ./.env && set +a ``` Create a [fine-grained personal access token](https://github.com/settings/tokens?type=beta) with: * **Repository access**: Select the repositories you want to analyze * **Permissions**: `Contents` (read), `Pull requests` (read), `Metadata` (read) Create a [personal access token](https://docs.gitlab.com/ee/user/profile/personal_access_tokens.html) with `api` scope. For self-hosted GitLab, also set the instance URL in the dashboard when adding the repository. Create an [app password](https://support.atlassian.com/bitbucket-cloud/docs/app-passwords/) or workspace access token with `repository:read` and `pullrequest:read` permissions. ```bash theme={null} docker run --rm -v /opt/navigara/keys:/keys \ "$COLLECTOR_IMAGE" \ ./collector keygen --out /keys ``` Writes `private.pem` (mode `0600`) and `public.pem` to `/opt/navigara/keys`, and prints the key fingerprint. Keep `private.pem` on this host — it is never shared. Mount the key and set `COLLECTOR_PRIVATE_KEY_PATH` in your `docker-compose.yml`, then restart: ```yaml theme={null} services: collector: environment: COLLECTOR_PRIVATE_KEY_PATH: /etc/navigara/keys/private.pem volumes: - ./keys/private.pem:/etc/navigara/keys/private.pem:ro ``` ```bash theme={null} echo -n 'ghp_yourtoken' | docker run --rm -i -v /opt/navigara/keys:/keys \ "$COLLECTOR_IMAGE" \ ./collector encrypt-token --public-key /keys/public.pem ``` Copy the `navigara-enc-v1:…` blob it prints. Add the blob as the provider token under **Settings → Connections → Source control** when connecting your Git account. Navigara stores it as-is and your next analysis run uses it automatically. To move an existing connection to encryption: mint a fresh token at your Git host, encrypt it, paste the blob, then revoke the old token. The collector can load several private keys at once. Comma-separate the paths in `COLLECTOR_PRIVATE_KEY_PATH`, or use `COLLECTOR_PRIVATE_KEY_PEM` for inline PEM. It selects the matching key per blob by fingerprint, so you can add a new key before you re-encrypt old tokens. If a blob does not decrypt, the collector drops it and fails the task. It never forwards an undecrypted blob to the Git host. For the full collector CLI reference (`keygen`, `encrypt-token`, `decrypt-token`) and key rotation, see [Encrypted Git Tokens](/deployment/encrypted-git-tokens). ## Installation ### 1. Prepare the host Install Docker from Docker's own package repository. Replace `ubuntu` with `debian` on a Debian host. Log out and back in for the group change to take effect. ```bash theme={null} sudo apt-get update sudo apt-get install -y ca-certificates curl sudo install -m 0755 -d /etc/apt/keyrings sudo curl -fsSL https://download.docker.com/linux/ubuntu/gpg -o /etc/apt/keyrings/docker.asc sudo chmod a+r /etc/apt/keyrings/docker.asc echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/ubuntu $(. /etc/os-release && echo "$VERSION_CODENAME") stable" \ | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null sudo apt-get update sudo apt-get install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin sudo usermod -aG docker $USER docker compose version ``` Do not use the `get.docker.com` convenience script. Docker does not support it for production installs. ### 2. Verify the release Verify the image before you run it. Navigara signs every released image and publishes an SBOM and build provenance alongside it. Install [cosign](https://docs.sigstore.dev/cosign/system_config/installation/), then verify the digest you intend to run: ```bash theme={null} cosign verify \ --certificate-identity-regexp "^https://github.com/navigaracom/vision/\.github/workflows/release\.yml@refs/tags/v" \ --certificate-oidc-issuer "https://token.actions.githubusercontent.com" \ "europe-docker.pkg.dev/navigara-images/public/vision-collector@sha256:4059d0733413e6f0c32a5d2ec1c9f8604e5061ae9b3ca0eaea39abd567a494fe" ``` The image also carries its provenance and a full SPDX package list. Feed them to your own scanner: ```bash theme={null} REF="europe-docker.pkg.dev/navigara-images/public/vision-collector@sha256:4059d0733413e6f0c32a5d2ec1c9f8604e5061ae9b3ca0eaea39abd567a494fe" docker buildx imagetools inspect "$REF" --format '{{ json .Provenance }}' docker buildx imagetools inspect "$REF" --format '{{ json .SBOM }}' ``` If `cosign verify` reports `no matching signatures`, **stop**. Either the version you pinned predates image signing — install the current release instead — or the image is not the one Navigara published. Contact support before running it. ### 3. Generate a Collector API Token In the Navigara dashboard, go to **Settings → API Tokens** and create a new API token. This token authenticates the collector with the Navigara backend. Copy it — you need it in the next step. ### 4. Configure the deployment Create the deployment directory: ```bash theme={null} mkdir -p /opt/navigara && cd /opt/navigara ``` Create `docker-compose.yml`. Keep the containment settings as written. The collector publishes no port. It dials out to Navigara, and nothing reaches it from outside. ```yaml theme={null} services: collector: image: ${COLLECTOR_IMAGE:?set COLLECTOR_IMAGE in .env to a digest-pinned reference} container_name: navigara-collector init: true env_file: - .env environment: SERVER_ADDR: ${SERVER_ADDR:-app.navigara.com:443} COLLECTOR_TLS: "true" COLLECTOR_ID: ${COLLECTOR_ID:-collector-1} COLLECTOR_API_KEY: ${COLLECTOR_API_KEY:?set COLLECTOR_API_KEY in .env} MAX_WORKERS: ${COLLECTOR_MAX_WORKERS:-10} LLM_PROVIDER: ${LLM_PROVIDER:-anthropic} LLM_MODEL: ${LLM_MODEL:-claude-sonnet-4-20250514} WORK_DIR: /tmp/git-analysis volumes: - collector-workdir:/tmp # Uncomment for a Vertex AI service account key file # - ./vertex-ai-key.json:/etc/navigara/vertex-ai-key.json:ro read_only: true cap_drop: - ALL security_opt: - "no-new-privileges:true" deploy: resources: limits: cpus: "${COLLECTOR_CPUS:-8.0}" memory: ${COLLECTOR_MEMORY:-8g} pids: 4096 restart: unless-stopped volumes: collector-workdir: name: navigara-collector-workdir ``` The `collector-workdir` volume holds full Git clones. Encrypt it if your policy requires encryption of source code at rest. Create a `.env` file: ```bash theme={null} NAVIGARA_VERSION=0.14.8 COLLECTOR_IMAGE=europe-docker.pkg.dev/navigara-images/public/vision-collector:0.14.8@sha256:d28a213910ed1a1e477836ddfdff4f49400a529127e5df1901200b4f4b9cd1e3 COLLECTOR_API_KEY= # COLLECTOR_ID=collector-1 # COLLECTOR_MAX_WORKERS=10 # COLLECTOR_CPUS=8.0 # COLLECTOR_MEMORY=8g LLM_PROVIDER=anthropic LLM_MODEL=claude-sonnet-4-20250514 LLM_API_KEY= LLM_API_URL=https://api.anthropic.com # OpenAI # LLM_PROVIDER=openai # LLM_MODEL=gpt-5.4 # LLM_API_KEY= # Google Vertex AI # LLM_PROVIDER=genai # LLM_MODEL=gemini-2.5-flash # GOOGLE_PROJECT= # GOOGLE_LOCATION=global # GOOGLE_APPLICATION_CREDENTIALS=/etc/navigara/vertex-ai-key.json ``` Pin `COLLECTOR_IMAGE` by digest. `LLM_API_URL` is required for `anthropic` and `openai`. Set `GOOGLE_APPLICATION_CREDENTIALS` only when the host has no `gcloud` authentication. ## LLM Configuration Navigara requires an LLM API endpoint for AI-powered commit analysis. Supported providers: | Provider | Model | Notes | | -------------------- | ---------------------------- | ------------------------------------- | | **Anthropic** | Claude Sonnet / Claude Haiku | Recommended — best quality/cost ratio | | **Google Vertex AI** | Gemini 2.5 Flash | Good cost/performance ratio | | **OpenAI** | GPT-5.4 | Widely available | ```bash theme={null} LLM_PROVIDER=anthropic LLM_MODEL=claude-sonnet-4-20250514 LLM_API_KEY= LLM_API_URL=https://api.anthropic.com ``` `LLM_API_URL` is required. Claude Haiku (`claude-haiku-4-5-20251001`) costs less and runs faster. For Azure AI Foundry, internal API gateways, or other Anthropic-Messages-API-compatible endpoints, set `LLM_API_URL` to that endpoint. Do **not** include `/v1` in the URL — the SDK appends `/v1/messages` itself. Vertex AI uses GCP service account authentication instead of a static API key. **1. Create a GCP service account** with the `Vertex AI User` role in your GCP project. **2. Download the service account key file** (e.g., `vertex-ai-key.json`) and place it on the host. **3. Set the following in your `.env` file:** ```bash theme={null} LLM_PROVIDER=genai LLM_MODEL=gemini-2.5-flash GOOGLE_PROJECT= GOOGLE_LOCATION=global GOOGLE_APPLICATION_CREDENTIALS=/etc/navigara/vertex-ai-key.json ``` **4. Mount the key file** in your `docker-compose.yml`: ```yaml theme={null} volumes: - ./vertex-ai-key.json:/etc/navigara/vertex-ai-key.json:ro ``` ```bash theme={null} LLM_PROVIDER=openai LLM_MODEL=gpt-5.4 LLM_API_KEY= ``` Any model served behind an OpenAI-compatible API (e.g., vLLM, Ollama) can be used: ```bash theme={null} LLM_PROVIDER=openai LLM_MODEL= LLM_API_KEY= LLM_API_URL=http://:8000/v1 ``` Your setup may not need `LLM_API_KEY`. ### 5. Start the collector ```bash theme={null} docker compose up -d ``` Verify the collector is running and connected: ```bash theme={null} docker compose logs -f collector ``` You should see output indicating a successful connection: ``` connected to server at app.navigara.com:443 registered as collector-1 with 10 workers ``` ### 6. Add repositories In the Navigara dashboard: 1. Go to **Settings → Repositories → Add Repository** 2. Select your Git provider and authenticate (if using cloud-managed tokens or GitHub App) 3. Select the repositories to analyze 4. The collector begins processing automatically ## Configuration Reference | Variable | Default | Description | | ---------------------------- | -------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `SERVER_ADDR` | `app.navigara.com:443` | Navigara API gRPC address | | `COLLECTOR_TLS` | `true` | Enable TLS for gRPC connection | | `COLLECTOR_API_KEY` | — | API token generated in Settings → API Tokens (required) | | `COLLECTOR_ID` | hostname | Unique identifier for this collector (defaults to container hostname) | | `MAX_WORKERS` | `10` | Number of concurrent commit analysis workers | | `LLM_PROVIDER` | `anthropic` | LLM provider: `anthropic`, `openai`, or `genai` | | `LLM_MODEL` | `claude-sonnet-4-20250514` | Model name | | `LLM_API_KEY` | — | API key for the LLM provider | | `LLM_API_URL` | — | LLM endpoint URL. **Required** for `anthropic` (e.g. `https://api.anthropic.com`) and `openai`. Also used for Azure Foundry, internal gateways, and self-hosted models. | | `GOOGLE_PROJECT` | — | GCP project ID (required for `genai` provider) | | `GOOGLE_LOCATION` | `global` | GCP location (for `genai` provider) | | `WORK_DIR` | `/tmp/git-analysis` | Directory for temporary Git clones | | `COLLECTOR_PRIVATE_KEY_PATH` | — | Path to a PEM private key for [encrypted tokens](#option-2-provider-tokens-end-to-end-encrypted-all-providers). Comma-separate multiple files for rotation. | | `COLLECTOR_PRIVATE_KEY_PEM` | — | Inline PEM private key(s) for encrypted tokens. Alternative to `COLLECTOR_PRIVATE_KEY_PATH`. | ## Running Multiple Collectors Run multiple collector instances for higher throughput or geographic distribution. Each collector must have a unique `COLLECTOR_ID`. The Navigara backend distributes work across connected collectors with affinity routing — it prefers a collector that already has the repository cached. ```yaml theme={null} services: collector-1: image: europe-docker.pkg.dev/navigara-images/public/vision-collector:${NAVIGARA_VERSION} container_name: navigara-collector-1 init: true env_file: .env environment: COLLECTOR_ID: collector-1 # ... other env vars restart: unless-stopped collector-2: image: europe-docker.pkg.dev/navigara-images/public/vision-collector:${NAVIGARA_VERSION} container_name: navigara-collector-2 init: true env_file: .env environment: COLLECTOR_ID: collector-2 # ... other env vars restart: unless-stopped ``` ## Network Requirements The collector host must have outbound access to the following services: | Service | Purpose | Endpoint | | ---------------- | ------------------------------------ | ------------------------------------------------------------- | | **Navigara API** | Work assignment and result streaming | `app.navigara.com:443` | | **Git provider** | Repository cloning and fetching | `github.com`, `gitlab.com`, or your self-hosted instance | | **LLM API** | AI-powered commit analysis | `api.anthropic.com`, `api.openai.com`, or Vertex AI endpoints | No inbound ports need to be opened. The collector initiates all connections outbound. ## Upgrades Verify the new release before you run it, exactly as you did at install. 1. Verify the new digest, as in [step 2](#2-verify-the-release). ```bash theme={null} cosign verify \ --certificate-identity-regexp "^https://github.com/navigaracom/vision/\.github/workflows/release\.yml@refs/tags/v" \ --certificate-oidc-issuer "https://token.actions.githubusercontent.com" \ "europe-docker.pkg.dev/navigara-images/public/vision-collector@sha256:" ``` 2. Update `NAVIGARA_VERSION` and `COLLECTOR_IMAGE` in `.env`, then restart. ```bash theme={null} cd /opt/navigara docker compose pull docker compose up -d ``` The collector is stateless. Stop and restart it at any time without data loss. The Navigara backend reassigns in-progress work. To roll back, put the previous digest back in `.env` and repeat. ### Emergency security releases Navigara ships an emergency release within **48 hours** for a vulnerability under active exploitation, and within **24 hours** for a compromise of Navigara-issued credentials. We notify the technical contact on your account directly in both cases. See [Full on-premises → Emergency security releases](/deployment/full-on-premises#emergency-security-releases) for the full policy and what to do on your side. ## Troubleshooting | Issue | Solution | | ---------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `connection refused` | Verify outbound access to `app.navigara.com:443` from the host | | `authentication failed` | Check that `COLLECTOR_API_KEY` matches the token configured in Navigara | | `LLM analysis failing` | Verify `LLM_API_KEY` and that the host can reach the LLM endpoint | | Collector keeps reconnecting | Check logs for specific errors; ensure the gRPC stream is not being terminated by a proxy or firewall | | Slow analysis | Increase `MAX_WORKERS` (ensure sufficient CPU/memory) or add a second collector | | `cosign verify` reports no matching signatures | The version you pinned predates image signing, or the image is not the one Navigara published. Install the current release; if that also fails, contact support before running it. | | Container restarts with a read-only filesystem error | The image needs a writable path this Compose file does not grant. Report it — do not remove `read_only`. Add a `tmpfs` entry for that path as a temporary measure. | | High disk usage | The collector caches Git clones in `WORK_DIR`; restart the container or clear the volume to reclaim space | # Deployment Options Source: https://docs.navigara.com/deployment/overview Choose the deployment model that fits your security and infrastructure requirements. Navigara offers three deployment options to match your organization's needs. ## Cloud SaaS Fully managed — no infrastructure needed. Data is processed and stored in Navigara's cloud. Get started with the cloud version. ## Cloud SaaS with On-Prem Collector SaaS frontend and API with an on-premise collector agent. Source code stays within your network — only metadata and analysis results are sent to the cloud. Deploy a collector inside your network. ## Full On-Premises All components deployed within your infrastructure. Complete data sovereignty with no external dependencies. Deploy the full Navigara stack. ## Securing your deployment Whichever model you choose, harden it before you go live. Network boundaries, identity, secrets, credentials, and data protection. # Introduction Source: https://docs.navigara.com/index Navigara analyzes your Git repositories and tracks developer metrics through AI-powered commit analysis. ## Welcome to Navigara Navigara helps engineering teams understand their codebase through AI-powered analysis. It tracks developer performance, code quality, and alignment between tasks and commits. Get up and running with Navigara in minutes. ## Explore Connect your Git providers and task management tools. Understand how Performance and Alignment scores work. Choose between cloud, hybrid, or full on-premises deployment. Integrate Navigara programmatically. # AI Coding Tools Source: https://docs.navigara.com/integrations/ai-tools Send usage telemetry from Claude Code, GitHub Copilot, OpenAI Codex, and LiteLLM into Navigara to measure AI adoption, cost, and impact. Navigara measures how your organization actually uses AI coding assistants — cost, tokens, models, and which developers are active — by ingesting **usage telemetry** from the tools themselves. Every AI tool emits [OpenTelemetry](https://opentelemetry.io) (OTLP), and Navigara exposes an OTLP endpoint that turns that stream into per-developer, per-model spend on the [Tool Spend](https://app.navigara.com/tool-spend) dashboard. **Any plan or license works — we support them all.** Ingestion is pure OpenTelemetry, independent of how you pay for the tool. There's nothing to buy or upgrade to be measured. **You control what leaves the workstation.** By default Navigara collects only **usage metadata** — session and user IDs, model, cost, token counts, durations, and tool names. Each tool's own telemetry flags let you opt into richer signals (prompt text, tool inputs/outputs, raw API bodies) — for Claude Code, for example, `OTEL_LOG_USER_PROMPTS`, `OTEL_LOG_TOOL_DETAILS`, `OTEL_LOG_TOOL_CONTENT`, and `OTEL_LOG_RAW_API_BODIES`. Send as much or as little as you choose. ## How it works ```mermaid theme={null} graph LR Tool["AI tool
(Claude Code / Copilot / Codex / LiteLLM)"] -->|OTLP/HTTP| OTLP["Navigara OTLP endpoint
/api/otlp"] OTLP -->|attributed by email| Spend["Tool Spend dashboard"] ``` 1. **You mint an ingest token** — a write-only API token scoped to your organization. 2. **You configure the tool** to export OTLP metrics (and logs, for identity) to Navigara's endpoint with that token as a bearer header. 3. **Navigara attributes usage to contributors** by email and materializes it into cost and token metrics. Usage shows up in **Tool Spend** within a few minutes. ## Set up a connection (recommended) The fastest path is the built-in wizard — it mints the token and generates the exact config for you: Go to **Settings → Connections**. Alongside **Source control** and **Task tracking**, there is an **AI tools** group — "Usage telemetry from AI coding assistants". Choose Claude Code, GitHub Copilot, OpenAI Codex, or LiteLLM, then give the connection a name (e.g. by team, region, or backend). You can add more than one connection per tool. Click **Generate token & config**. Navigara mints a write-only ingest token and drops it into a ready-to-copy config block. The token is shown once — copy it now. (Use **Preview config** to see the snippet with a `` placeholder without minting anything.) Apply the config to your workstations, fleet, or proxy using the per-tool instructions below. Usage appears in **Tool Spend** within a few minutes. ## The ingest endpoint and token If you'd rather wire it up by hand, everything the wizard produces comes down to two values. **Endpoint** — Navigara serves OTLP/HTTP at `/api/otlp`. OTLP clients append the signal path (`/v1/metrics`, `/v1/logs`) themselves. | Deployment | OTLP endpoint | | ----------------- | ----------------------------------------- | | Cloud SaaS | `https://app.navigara.com/api/otlp` | | Full on-premises | `https:///api/otlp` | | On-prem collector | `http://:/otlp` | **Ingest token** — create one at **Settings → API Tokens → Create API Token**. Any token works, but a dedicated **Ingest only** token (write-only, cannot read your data) is recommended; the AI-tools wizard mints exactly this. Pass it on every request as: ``` Authorization: Bearer ``` **Identity is matched by email.** Navigara joins usage to a contributor using the email the tool reports. Where a tool can't emit an email natively, the snippets below set `enduser.id` (usually from the developer's git email) — make sure it matches the email Navigara already knows the contributor by. Usage that can't be matched still counts toward org totals; it just shows as unattributed until an email resolves. *** ## Claude Code Claude Code has native OpenTelemetry support. It emits cost and token **metrics**, and — on Claude.ai (Team / Enterprise) sign-in — the developer's email, account, and organization IDs on **logs**, which is how usage is attributed. Ship this file via MDM so developers can't override it: * macOS: `/Library/Application Support/ClaudeCode/managed-settings.json` * Linux: `/etc/claude-code/managed-settings.json` * Windows: `C:\Program Files\ClaudeCode\managed-settings.json` ```json theme={null} { "env": { "CLAUDE_CODE_ENABLE_TELEMETRY": "1", "OTEL_METRICS_EXPORTER": "otlp", "OTEL_LOGS_EXPORTER": "otlp", "OTEL_EXPORTER_OTLP_PROTOCOL": "http/protobuf", "OTEL_EXPORTER_OTLP_ENDPOINT": "https://app.navigara.com/api/otlp", "OTEL_EXPORTER_OTLP_HEADERS": "Authorization=Bearer " } } ``` Add to the shell profile or a `claude` launcher wrapper: ```bash theme={null} export CLAUDE_CODE_ENABLE_TELEMETRY="1" export OTEL_METRICS_EXPORTER="otlp" export OTEL_LOGS_EXPORTER="otlp" export OTEL_EXPORTER_OTLP_PROTOCOL="http/protobuf" export OTEL_EXPORTER_OTLP_ENDPOINT="https://app.navigara.com/api/otlp" export OTEL_EXPORTER_OTLP_HEADERS="Authorization=Bearer " ``` ### Attribution by auth model * **Claude.ai sign-in (Team / Enterprise)** — Claude Code emits the user's email and account IDs natively. Nothing else to add. * **API key / Bedrock / Vertex** — only an anonymous installation ID is emitted, so set `enduser.id` yourself. Because managed settings are identical on every machine, this belongs in a per-developer launcher, not the shared JSON: ```bash theme={null} # enduser.id is how usage gets attributed to a developer under API key / Bedrock / Vertex auth. attrs="enduser.id=${USER}" if git rev-parse --git-dir >/dev/null 2>&1; then attrs+=",git.branch=$(git symbolic-ref --short HEAD 2>/dev/null || echo detached)" attrs+=",git.repo=$(basename "$(git rev-parse --show-toplevel)")" attrs+=",git.commit=$(git rev-parse --short HEAD)" fi export OTEL_RESOURCE_ATTRIBUTES="$attrs" ``` *** ## GitHub Copilot Copilot CLI telemetry is off by default. Copilot configures OTLP through **environment variables only** — its `~/.copilot/config.json` has no telemetry settings — so for a fleet-wide rollout drop these into a shared profile (e.g. `/etc/profile.d/`) or a `copilot` launcher wrapper. ```bash theme={null} export COPILOT_OTEL_ENABLED="true" export OTEL_EXPORTER_OTLP_ENDPOINT="https://app.navigara.com/api/otlp" export OTEL_EXPORTER_OTLP_PROTOCOL="http/json" export OTEL_EXPORTER_OTLP_HEADERS="Authorization=Bearer " # Copilot emits no developer identity on any stream — enduser.id is the only # attribution lever, matched to a contributor by email. Defaults to your git # email; override if that isn't the email Navigara knows you by. export OTEL_RESOURCE_ATTRIBUTES="enduser.id=$(git config user.email)" ``` Copilot CLI does not ship protobuf export yet, so the protocol is pinned to `http/json` — the encoding Navigara accepts for Copilot. *** ## OpenAI Codex Codex configures OTLP through `~/.codex/config.toml`, not environment variables. Telemetry is off by default; this turns on its OTLP exporter and points it at Navigara. Usage rides **metrics**; identity rides **logs**. ```toml theme={null} # ~/.codex/config.toml [otel.metrics_exporter.otlp-http] endpoint = "https://app.navigara.com/api/otlp/v1/metrics" protocol = "binary" headers = { Authorization = "Bearer " } [otel.exporter.otlp-http] endpoint = "https://app.navigara.com/api/otlp/v1/logs" protocol = "binary" headers = { Authorization = "Bearer " } ``` Codex token-usage metrics carry no developer identity, so set `enduser.id` per workstation. It's a per-developer value, so it belongs in the shell profile, not the shared config file: ```bash theme={null} export OTEL_RESOURCE_ATTRIBUTES="enduser.id=$(git config user.email)" ``` Codex sets `service.name` per surface (`codex_exec`, `codex_tui`); Navigara collapses these to one `codex` source automatically. *** ## LiteLLM Run one LiteLLM proxy in front of your providers and Navigara captures **proxy-wide** token and cost usage for every tool that routes through it. Requires **LiteLLM 1.89 or newer** — earlier proxies read `OTEL_ENDPOINT` instead and don't append the `/v1/metrics` path, so usage won't arrive. ```yaml theme={null} litellm_settings: callbacks: ["otel"] ``` ```bash theme={null} # The otel callback ships spans by default; metrics (token + cost) are opt-in. export LITELLM_OTEL_INTEGRATION_ENABLE_METRICS="true" export OTEL_EXPORTER="otlp_http" export OTEL_EXPORTER_OTLP_ENDPOINT="https://app.navigara.com/api/otlp" export OTEL_HEADERS="Authorization=Bearer " ``` Pick whichever matches how developers authenticate to the proxy. All three land the email in `metadata.user_api_key_*`, which Navigara resolves to a contributor. Mint a virtual key per developer (`/key/generate` or `/user/new`) and set that user's `user_email` to their git/commit email. LiteLLM exports it as `metadata.user_api_key_user_email`. Developers present their SSO token; LiteLLM extracts the email claim. Add to the same `config.yaml`, pointing at whichever claim holds the email: ```yaml theme={null} general_settings: enable_jwt_auth: true litellm_jwtauth: user_email_jwt_field: "email" ``` Each client sets the OpenAI-compatible `user` field to the developer's email. LiteLLM exports it as `metadata.user_api_key_end_user_id`. Cheapest option — nothing to manage in LiteLLM, but every calling tool must set `user`: ```bash theme={null} curl $LITELLM_PROXY/v1/chat/completions \ -H "Authorization: Bearer $YOUR_LITELLM_KEY" \ -d '{ "model": "gpt-4o", "messages": [{"role": "user", "content": "..."}], "user": "dev@yourcompany.com" }' ``` *** ## Troubleshooting * **Nothing in Tool Spend after a few minutes** — confirm the endpoint ends in `/api/otlp` (no `/v1/...` suffix except where a tool takes a full per-signal path, like Codex), and that the `Authorization` header carries a valid ingest token. Restart the tool/proxy so it re-reads its config. * **Usage shows up as unattributed** — the tool isn't emitting a resolvable email. For Copilot and Codex, set `OTEL_RESOURCE_ATTRIBUTES="enduser.id=..."`; for Claude Code under API-key auth, add the `enduser.id` launcher; for LiteLLM, wire one of the three identity models. The email must match the contributor's known email. * **Attribution resolves a day or two late** — Navigara re-attributes a trailing window automatically, so late-arriving emails backfill without action. * **LiteLLM sends traces but no cost/tokens** — set `LITELLM_OTEL_INTEGRATION_ENABLE_METRICS=true` and upgrade to LiteLLM ≥ 1.89. * **Copilot export fails on protobuf** — keep `OTEL_EXPORTER_OTLP_PROTOCOL=http/json`; the CLI doesn't ship protobuf export yet. # Supported Integrations Source: https://docs.navigara.com/integrations/overview Git providers, task management, authentication, and AI/LLM backends Navigara connects to. Navigara connects to the tools your engineering organization already uses. This page lists every supported integration with setup, required permissions, and common troubleshooting. ## At a glance | Category | Providers | | --------------------------- | --------------------------------------------------------- | | Git | GitHub, GitLab, Bitbucket, Bitbucket Server, Azure DevOps | | Task management | Linear, Jira Cloud, Jira Server / Data Center, Asana | | AI coding tools | Claude Code, GitHub Copilot, OpenAI Codex, LiteLLM | | Authentication | Google, GitHub, GitLab, Microsoft, email/password | | User provisioning | SCIM 2.0 — Okta, Microsoft Entra ID | | AI / LLM (analysis backend) | Google Vertex AI, AWS Bedrock, Azure AI Foundry | Git, task-management, and AI-coding-tool connections are managed from a single **Settings → Connections** page, which lists everything Navigara reads from in three groups — **Source control**, **Task tracking**, and **AI tools**. Each group has its own **Add connection** button. Authentication, SCIM, and the AI/LLM analysis backend are configured separately, as noted in their sections below. *** ## Git providers Navigara analyses commits, pull requests, and repository activity. Read-only access is sufficient for every provider. Add any of these from **Settings → Connections → Source control → Add connection**. ### GitHub Cloud (github.com) and GitHub Enterprise Server. **Setup** 1. **Settings → Connections → Source control → Add connection → GitHub**. 2. Install the Navigara GitHub App on the target organization. 3. Select the repositories to analyse (or grant access to all). **Required permissions** * Repository contents (read) * Pull requests (read) * Metadata (read) **Troubleshooting** * *Repos not showing up*: the GitHub App needs to be installed at the org level, not a personal account. Re-run the install flow and pick the right target. * *Enterprise Server*: set the instance URL when prompted. The App must be installed on the Enterprise instance, not github.com. ### GitLab GitLab.com and self-hosted (CE/EE). **Setup** 1. **Settings → Connections → Source control → Add connection → GitLab**. 2. For self-hosted, enter your GitLab instance URL. 3. Authorize via OAuth, or provide a personal/group access token. **Required permissions / scopes** * `read_api`, `read_repository`, `read_user` **Troubleshooting** * *401 on self-hosted*: confirm the instance URL has no trailing path and that the token has `read_api`. * *Missing projects*: the token or OAuth user must be a member of the projects — group-level tokens only see projects within that group. ### Bitbucket Bitbucket Cloud (bitbucket.org). **Setup** 1. **Settings → Connections → Source control → Add connection → Bitbucket**. 2. Create a workspace access token or app password in Bitbucket and paste it. **Required permissions / scopes** * `repository:read`, `pullrequest:read`, `account:read` **Troubleshooting** * *403 on pull requests*: app passwords require the `pullrequest` scope explicitly — regenerate with that box ticked. ### Bitbucket Server (self-hosted) Bitbucket Data Center / Server. **Setup** 1. **Settings → Connections → Source control → Add connection → Bitbucket Server**. 2. Enter the instance URL and an HTTP access token. **Required permissions** * Project read + Repository read on each project to analyse. **Troubleshooting** * *TLS errors*: ensure the instance certificate chain is trusted by the Navigara deployment. For on-prem, mount your CA bundle. ### Azure DevOps Azure DevOps Services (dev.azure.com). **Setup** 1. **Settings → Connections → Source control → Add connection → Azure DevOps**. 2. Authorize via Microsoft Entra ID (recommended) or provide a personal access token. **Required permissions / scopes** * `vso.code`, `vso.code_status`, `vso.identity`, `vso.profile` **Troubleshooting** * *Entra ID tenant mismatch*: the signed-in user must belong to the same tenant as the Azure DevOps organization. Sign in with a directory user, not a personal Microsoft account. *** ## Task management Task-tracking connections power **Alignment** scoring by correlating commits and PRs with the work items they deliver. They are managed from the **Task tracking** group on the **Settings → Connections** page. ### How connecting works Click **Add connection** in the **Task tracking** group and pick a provider. The dialog splits options into two categories: * **OAuth** — authorizes the connected user's workspace. Available for **Linear** and **Jira Cloud** when an OAuth application is configured for your Navigara deployment (always available on the cloud platform). * **Tokens** — a personal access token or API key. Best for self-hosted instances (Jira Server / Data Center), providers without OAuth (Asana), or service accounts. Token credentials are validated against the provider before they are saved. A provider already connected is shown as **Already connected** and cannot be added twice. ### The setup wizard The first time you connect a tracker — and any time afterwards via **Configure** on its row — a short wizard tailors what Navigara ingests: 1. **Scope** — sync **all** teams/projects in the workspace (including ones added later), or only a **selected** subset. Linear is scoped by **team**; Jira and Asana by **project**. 2. **Issue-type mapping** — place each issue type on the alignment ladder so Navigara knows how work rolls up: | Tier | Meaning | | ----------------- | ---------------------------------------------------------- | | **Objective** | Top-level goal (e.g. Linear initiative, Jira epic) | | **Sub-objective** | A grouping under an objective (e.g. project, parent story) | | **Issue** | A unit of delivered work that commits map to | | **Ignored** | Excluded from alignment entirely | Suggestions are pre-filled from each provider's hierarchy; adjust as needed. Saving the wizard for the first time enqueues the initial sync. Re-running it only updates settings. ### Linear **Setup** 1. **Settings → Connections → Task tracking → Add connection → Linear**. 2. Either authorize the Navigara OAuth application (**OAuth**), or paste a personal API key created under [Linear → Settings → Security & access](https://linear.app/settings/account/security) (**Tokens**). 3. Complete the setup wizard — scope by team and confirm the issue-type mapping. **Required permissions / scopes** * `read` on issues, projects, and teams **Troubleshooting** * *Issues not linking*: Alignment relies on issue identifiers (e.g. `ENG-123`) appearing in commit messages, branch names, or PR titles. ### Jira Cloud **Setup** 1. **Settings → Connections → Task tracking → Add connection → Jira Cloud**. 2. Either authorize with your Atlassian account (**OAuth**), or provide the site URL (e.g. `https://acme.atlassian.net`), your Atlassian account email, and an API token (**Tokens**). 3. Complete the setup wizard — scope by project and confirm the issue-type mapping. **API token types** API tokens are created at [id.atlassian.com](https://id.atlassian.com/manage-profile/security/api-tokens). All three variants work: * **Scoped token with classic scopes** ("Create API token with scopes" → Jira) — grant `read:jira-work` and `read:jira-user`. **Recommended** — the simplest option that still follows least-privilege. * **Unscoped token** ("Create API token") — no scopes to configure and covers everything, but grants the token your full account access. It works, but scoped tokens are the better practice. * **Scoped token with granular scopes** — grant the full read-only set below. A missing scope can fail validation or return incomplete issue data, so grant all of them: ``` read:user:jira read:project:jira read:project-category:jira read:project-version:jira read:project.component:jira read:project.property:jira read:issue-details:jira read:issue-type:jira read:issue-type-hierarchy:jira read:field:jira read:field.default-value:jira read:field.option:jira read:group:jira read:avatar:jira read:application-role:jira ``` **Required permissions** * Browse projects, View issues on each synced project. OAuth scopes never override Jira project permissions. **Troubleshooting** * *401*: pair the token with the account email as the username. For a **scoped** token, confirm its scopes are granted in full (`read:jira-work` + `read:jira-user` for classic, or the complete granular set) — a missing user scope fails validation with a 401, and other missing scopes surface as empty or partial issue data. ### Jira (Server / Data Center) Self-hosted Jira. **Setup** 1. **Settings → Connections → Task tracking → Add connection → Jira (Server / Data Center)**. 2. Provide your Jira base URL (e.g. `https://jira.acme.corp`) and a [personal access token](https://confluence.atlassian.com/enterprise/using-personal-access-tokens-1026032365.html). 3. Complete the setup wizard — scope by project and confirm the issue-type mapping. **Required permissions** * Browse projects, View issues on each synced project. **Troubleshooting** * *403*: the PAT owner needs at least "Browse Projects" permission on every project you intend to sync. ### Asana **Setup** 1. **Settings → Connections → Task tracking → Add connection → Asana**. 2. Paste a personal access token created in the [Asana developer console](https://app.asana.com/0/my-apps). 3. Complete the setup wizard — scope by project and confirm the issue-type mapping. **Required permissions** * The token owner must be a member of the projects you intend to sync. **Troubleshooting** * *Missing projects*: Asana personal access tokens only see workspaces and projects the token owner belongs to — add them to the project, or use a service-account token with the right membership. *** ## AI coding tools Navigara measures how your team uses AI coding assistants — cost, tokens, models, and active developers — by ingesting **usage telemetry** the tools emit over OpenTelemetry (OTLP). Add these from the **AI tools** group on the **Settings → Connections** page; each connection mints a write-only ingest token and generates the exact config to drop into the tool. | Tool | How usage arrives | | ------------------ | ---------------------------------------------------------------- | | **Claude Code** | Native OTLP — env vars or MDM managed settings | | **GitHub Copilot** | Copilot CLI OTLP env vars | | **OpenAI Codex** | `~/.codex/config.toml` OTLP exporter | | **LiteLLM** | Proxy-wide OTel callback (one proxy covers every tool behind it) | **Any plan or license works — we support them all.** Ingestion is pure OpenTelemetry, independent of how you pay for the tool. You control what leaves the workstation: by default only usage metadata, with per-tool flags to opt into prompt and tool content. See the dedicated [AI Coding Tools](/integrations/ai-tools) page for complete, copy-pasteable setup for each tool, the ingest endpoint, and attribution. This is distinct from the [AI / LLM](#ai-llm) section below, which configures the LLM backend Navigara uses to *analyze* your commits. Here, the AI tools are the *subject* being measured. *** ## Authentication How users sign in to Navigara. Multiple methods can be enabled simultaneously; on-prem deployments pick which ones are exposed. ### Google **Setup** 1. Create an OAuth 2.0 client in Google Cloud Console. 2. Add `https:///api/auth/callback/google` as an authorized redirect URI. 3. Set `GOOGLE_OAUTH_CLIENT_ID` and `GOOGLE_OAUTH_CLIENT_SECRET`. **Required scopes** * `openid`, `email`, `profile` ### GitHub **Setup** 1. Create an OAuth App under GitHub Developer Settings. 2. Set the callback URL to `https:///api/auth/callback/github`. 3. Set `GITHUB_OAUTH_CLIENT_ID` and `GITHUB_OAUTH_CLIENT_SECRET`. **Required scopes** * `read:user`, `user:email` ### GitLab **Setup** 1. Create an OAuth application in GitLab (User → Preferences → Applications, or group-level). 2. Set the redirect URI to `https:///api/auth/callback/gitlab`. 3. Set `GITLAB_OAUTH_CLIENT_ID` and `GITLAB_OAUTH_CLIENT_SECRET`. **Required scopes** * `read_user`, `openid`, `email` ### Microsoft (Entra ID) **Setup** 1. Register an application in Microsoft Entra ID. 2. Add `https:///api/auth/callback/microsoft` as a redirect URI. 3. Set `MICROSOFT_OAUTH_CLIENT_ID` and `MICROSOFT_OAUTH_CLIENT_SECRET`. **Required scopes** * `openid`, `email`, `profile`, `User.Read` ### Email and password Disabled by default. Set `ENABLE_PASSWORD_AUTH=true` in the backend environment to expose the email/password form. Intended for local development and isolated on-prem deployments where SSO is not available. *** ## User provisioning (SCIM) Keep your contributor directory in sync with your identity provider over SCIM 2.0. Your IdP pushes users to Navigara, and role, seniority, and manager metadata flow onto the matching contributors automatically. Navigara implements standard SCIM 2.0; setup steps are provided for **Okta** and **Microsoft Entra ID**. See the dedicated [SCIM Provisioning](/integrations/scim) page for token setup, IdP configuration, attribute mapping, and troubleshooting. SCIM enriches contributor profiles — it does not grant sign-in access. Users still authenticate through SSO or an invite. *** ## AI / LLM Navigara uses LLMs for commit analysis, summaries, and AI-generated code detection. Any of the backends below works; **we recommend Anthropic Claude models** (Opus / Sonnet / Haiku) for the best analysis quality. ### Google Vertex AI (recommended default) Native integration. Runs Gemini models directly and Anthropic Claude models via [Vertex AI Model Garden](https://cloud.google.com/vertex-ai/generative-ai/docs/partner-models/use-claude). **Configuration** ```bash theme={null} LLM_PROVIDER=vertexai LLM_MODEL=claude-sonnet-4-6 # recommended # or: gemini-2.5-flash for a Google-only stack GOOGLE_PROJECT=your-gcp-project GOOGLE_LOCATION=global ``` Authentication uses Application Default Credentials — the runtime service account needs `roles/aiplatform.user`. **Claude on Vertex**: Anthropic models are only available in specific regions (e.g. `us-east5`). Navigara handles region routing automatically when a `claude-*` model is selected. ### AWS Bedrock Connect via Bedrock's OpenAI-compatible endpoint. Anthropic Claude models are available through Bedrock and are the recommended choice. **Configuration** ```bash theme={null} LLM_PROVIDER=openai LLM_MODEL=anthropic.claude-sonnet-4-6-v1:0 LLM_API_KEY= LLM_API_URL=https://bedrock-runtime..amazonaws.com/openai/v1 ``` The IAM principal backing the API key needs `bedrock:InvokeModel` on the target model and must have the model enabled in that region. ### Azure AI Foundry Foundry exposes Claude under the Anthropic Messages API and OpenAI / GPT models under Azure OpenAI. Use the matching provider for each model family. **Anthropic Claude on Foundry** ```bash theme={null} LLM_PROVIDER=anthropic LLM_MODEL=claude-sonnet-4-6 LLM_API_KEY= LLM_API_URL=https://.services.ai.azure.com/anthropic ``` The Anthropic SDK appends `/v1/messages` to `LLM_API_URL` — set the URL to the `…/anthropic` base, **not** to the full `…/anthropic/v1/messages`. **OpenAI / GPT on Foundry** ```bash theme={null} LLM_PROVIDER=openai LLM_MODEL= LLM_API_KEY= LLM_API_URL=https://.openai.azure.com/openai/responses?api-version=2025-04-01-preview ``` Navigara detects `.openai.azure.com` and `.cognitiveservices.azure.com` URLs and switches to Azure authentication automatically. Create a deployment in Azure AI Foundry and use the deployment name as `LLM_MODEL`. ### Custom API gateways If your organization fronts LLM providers behind an API management layer (Azure API Management, AWS API Gateway, internal proxies), use `LLM_PROVIDER=anthropic` for any Anthropic-Messages-API endpoint and `LLM_PROVIDER=openai` for any OpenAI-compatible endpoint. The model name is opaque — gateways may expose Claude under custom identifiers. ```bash theme={null} # Example: Anthropic Messages API behind a custom gateway LLM_PROVIDER=anthropic LLM_API_URL=https://api.example.com/foundry/claude-sonnet-4-6 LLM_API_KEY= LLM_MODEL=claude-sonnet-4-6 ``` Do not include `/v1` in `LLM_API_URL` — the Anthropic SDK appends `/v1/messages` itself. A URL ending in `/v1` produces `/v1/v1/messages` and the gateway will return 404. ### Troubleshooting * *401 / 403*: verify the API key, and for Vertex AI confirm the service account has `roles/aiplatform.user`. * *404 on model*: the model must be explicitly enabled/deployed in your cloud account (Bedrock model access, Azure deployment, Vertex Model Garden activation). * *Region errors for Claude on Vertex*: Claude models only run in specific Vertex regions. Leave `GOOGLE_LOCATION=global` and Navigara will route correctly. * *Slow responses / rate limits*: tune `MAX_CONCURRENT_TASKS` in the backend to stay within your provider's quota. # SCIM Provisioning Source: https://docs.navigara.com/integrations/scim Keep your Navigara contributor directory in sync with Okta, Microsoft Entra ID, or any SCIM 2.0 identity provider. Navigara is a SCIM 2.0 **service provider**: your identity provider (IdP) pushes its user directory to Navigara, and Navigara keeps the contributor directory in sync automatically. When someone joins, changes role, or leaves in your IdP, that change flows into Navigara without manual upkeep. SCIM provisions the **contributor directory** — names, emails, role, seniority, and manager relationships used for grouping and metrics. It does **not** grant sign-in access. People still log in through your configured SSO (Google, GitHub, GitLab, Microsoft) or an invite. Provisioning a user over SCIM enriches their contributor profile; it does not create a login. ## What you get * **Automatic directory sync** — users created, updated, and deactivated in your IdP are reflected in Navigara. * **Attribute mapping** — map any IdP attribute (job title, department, manager, custom claims) onto Navigara contributor fields and tags. * **Identity stitching** — SCIM users are matched to the `git` contributors discovered from commit history, so directory metadata lands on the right person. ## Identity providers Navigara implements standard SCIM 2.0, so any compliant identity provider can connect. The steps below cover **Okta** and **Microsoft Entra ID**. Navigara also normalizes the common deviations between providers — including **Authentik** and **Ping Identity** — so quirks such as Entra sending `active` as a string, Okta's non-standard deactivation, and bare-string `manager` values are handled automatically, with no configuration required. **Configure user provisioning today.** Navigara does not yet map SCIM Groups onto Navigara teams. Configure **user provisioning** in your IdP; group push can stay off. Team membership is managed inside Navigara. ## Setup In Navigara, go to **Settings → SCIM** and create a token under the **Tokens** section. Give it a recognizable name (e.g. `okta-production`). The full token is shown **once**, at creation time — copy it immediately. It is prefixed with `scim_`. You can optionally set an expiry (30 days, 90 days, 1 year, or never). Treat the token like a password. It is a bearer credential that lets your IdP write to your organization's directory. If it leaks, revoke it from the same screen and mint a new one. The SCIM base URL is shown on the same screen. It is: ``` https:///api/scim/v2 ``` For Navigara Cloud that is `https://app.navigara.com/api/scim/v2`. For on-prem, substitute your own host. In your IdP, create a SCIM 2.0 provisioning app and point it at the endpoint above, using the token as a **Bearer** credential. Provider-specific steps below. Out of the box Navigara maps email, name, external ID, and manager. To map job title to a role, or any other attribute to a custom tag, use **Settings → SCIM → Attribute mapping**. See [Attribute mapping](#attribute-mapping). ### Identity provider configuration 1. In the Okta admin console, open **Applications → Create App Integration → SCIM 2.0** (or enable provisioning on an existing app). 2. Under **Provisioning → Integration**: * **SCIM connector base URL**: `https:///api/scim/v2` * **Unique identifier field for users**: `userName` (email) * **Supported provisioning actions**: enable **Push New Users**, **Push Profile Updates**, and **Push User Deactivation**. * **Authentication Mode**: HTTP Header → `Authorization: Bearer scim_…` 3. Click **Test Connector Configuration**, then save. 4. Under **Provisioning → To App**, enable **Create Users**, **Update User Attributes**, and **Deactivate Users**. 5. Assign the users (or groups of users) you want provisioned to the app. Okta's "Push Groups" tab is for syncing group membership. Since Navigara does not yet map SCIM groups to teams, you can leave Push Groups off and rely on user provisioning. 1. In the Entra admin center, go to **Enterprise applications → New application → Create your own application**, then open **Provisioning**. 2. Set **Provisioning Mode** to **Automatic**. 3. Under **Admin Credentials**: * **Tenant URL**: `https:///api/scim/v2` * **Secret Token**: your `scim_…` token 4. Click **Test Connection**, then save. 5. Under **Mappings**, keep **Provision Microsoft Entra ID Users** enabled. You can disable **Provision Microsoft Entra ID Groups**. 6. Assign users to the application and turn **Provisioning Status** to **On**. Entra sends some attributes (such as `active`) in non-standard shapes and uses value-path filters when an attribute like a work email changes. Navigara handles both automatically. ## What gets synced When your IdP pushes a user, Navigara reflects it onto a contributor: | SCIM resource | Result in Navigara | | ------------------------------ | --------------------------------------------------------------------------------- | | User | A contributor profile, matched to the `git` contributor with the same email | | User attributes | Contributor name, email, and tags (role, seniority, manager, …) per your mappings | | Deactivation (`active: false`) | The user is marked inactive; their commit history is preserved | | Group | **Not yet** mapped to Navigara teams | ### Identity stitching Navigara's metrics are tied to `git` contributors discovered from commit history. A SCIM user is automatically linked to a contributor when their **email** matches. When the IdP email differs from the email used in commits, link them manually: 1. Go to **Settings → SCIM → Attribute mapping** and open the **Linked users** tab. 2. Find the SCIM user and pick the matching contributor. Each SCIM user links to exactly one contributor and vice versa. The **Unmapped** tab lists SCIM users that have not yet been matched to a contributor. ## Attribute mapping **Settings → SCIM → Attribute mapping** controls how IdP attributes become contributor fields and tags. * **Field mapping** — map a source path in the SCIM payload (for example `name.formatted`, or `title` for job title) onto a target: `email`, `name`, `external_id`, or any `tags.`. Each mapping can lowercase the value and remap raw values to canonical ones (for example, fold "SW Eng I", "SW Eng II", and "SW Eng III" into a single `SWE`). * **Preview** — run the current (even unsaved) mappings against the latest data your IdP sent, to see exactly what each contributor field would become, plus warnings for missing required fields or non-string sources. If you save no mappings, Navigara applies sensible defaults: `userName` → email (lowercased), `name.formatted` → name, `externalId` → external ID, and the manager reference is recorded for directory relationships. You can map to any `tags.` you like. Two keys are recognized by Navigara's filters and dashboards today, and the mapping UI suggests their canonical values: | Tag | Sourced from | Suggested values | | ---------------------- | ----------------- | ---------------------------------------- | | `tags.role` | job title | `SWE`, `External SWE`, `Product Manager` | | `tags.seniority_level` | level / job title | `Junior`, `Medior`, `Senior` | Saving mappings re-syncs every live SCIM user against the new configuration. Tag keys you remove from the mappings are also removed from contributors on the next sync. ## Token management SCIM tokens are managed per organization under **Settings → SCIM → Tokens**: * **Create** — mint a named token, optionally with an expiry. The raw value is shown once. * **List** — see each token's name, prefix, creation date, last-used time, and expiry. The full secret is never shown again. * **Revoke** — disable a token immediately. Revocation is instant and irreversible; the IdP will start receiving `401` responses. An organization can hold up to **25 active tokens** at a time. Use separate tokens per IdP or environment so you can rotate one without disrupting the others. ## Troubleshooting The token is wrong, disabled, or expired. Confirm the IdP sends `Authorization: Bearer scim_…` (the header value must include the `Bearer ` prefix and the full token), and check the token still appears as enabled under **Settings → SCIM → Tokens**. If in doubt, mint a fresh token and update the IdP. The SCIM user has not been matched to a `git` contributor. This happens when the IdP email differs from the email used in commits. Open **Settings → SCIM → Attribute mapping → Linked users** and link them manually, or add the commit email as an alias on the contributor. Use the **Preview** tab to confirm the email mapping is producing the value you expect. The relevant attribute isn't mapped. Open **Attribute mapping → Field mapping** and add a mapping from the IdP source path to the target tag (e.g. `tags.role`). Use **Preview** against the latest payload to verify, then save — saving re-syncs existing users. Expected. Navigara receives SCIM groups but does not yet project them onto teams — manage team membership inside Navigara. If you rely on a group-derived attribute (e.g. department), make sure your IdP includes it on the **user** payload rather than only on the group. Navigara normalizes the common provider-specific deviations (Entra's string `active`, value-path PATCH on changed emails; Okta's deactivation via `remove` and bare-string `manager`) automatically. If a specific attribute still isn't landing, check it under **Attribute mapping → Preview** and contact [support@navigara.com](mailto:support@navigara.com). # Quickstart Source: https://docs.navigara.com/quickstart Get up and running with Navigara's cloud platform in minutes. This guide covers the cloud SaaS version. For self-hosted options, see [Deployment](/deployment/overview). ## 1. Sign up Create your account at [app.navigara.com](https://app.navigara.com) using email, Google, or GitHub authentication. ## 2. Create an organization After signing in, create your organization. This is the top-level container for all your repositories, teams, and settings. ## 3. Connect your Git provider Navigate to **Settings → Connections**. Everything Navigara reads from lives on this one page, grouped into **Source control** and **Task tracking**. Under **Source control**, click **Add connection** and pick your provider: * **GitHub** — install the Navigara GitHub App (or paste a personal access token) * **GitLab** — OAuth, or a personal/group access token * **Bitbucket** — workspace access token or app password * **Azure DevOps** — Microsoft Entra ID OAuth, or a personal access token Read-only access is sufficient for every provider. See [Integrations](/integrations/overview#git-providers) for required scopes. ## 4. Connect task management (optional) Task tracking powers **Alignment** scoring by correlating commits and PRs with the work items they deliver. Under the **Task tracking** section of the same **Settings → Connections** page, click **Add connection** and pick a provider: * **Linear** — authorize via OAuth, or paste a personal API key * **Jira Cloud** — authorize with your Atlassian account, or provide a site URL + API token * **Jira (Server / Data Center)** — base URL + personal access token * **Asana** — personal access token After the credentials are validated, a short **setup wizard** opens so you can: 1. **Choose scope** — sync all teams/projects in the workspace, or just a selected subset. 2. **Map issue types** — place each issue type on the alignment ladder: **Objective**, **Sub-objective**, **Issue**, or **Ignored**. Suggestions are pre-filled, and you can re-open the wizard anytime to adjust scope or mappings. Saving the wizard for the first time kicks off the initial sync. ## 5. Track AI coding tool usage (optional) See how your team actually uses AI assistants — cost, tokens, models, and which developers are active — on the **Tool Spend** dashboard. Under the **AI tools** section of the same **Settings → Connections** page, pick a tool and click **Generate token & config**: Navigara mints a write-only ingest token and hands you a ready-to-copy config that ships usage telemetry over OpenTelemetry (OTLP). You control what leaves the workstation — by default only usage metadata (cost, tokens, models, durations, tool names), with per-tool flags to opt into prompt and tool content. **Any plan or license works — we support them all.** Ingestion is pure OpenTelemetry, independent of how you pay for the tool. There's nothing to buy or upgrade to be measured. The complete examples below use the cloud endpoint `https://app.navigara.com/api/otlp`; self-hosted deployments substitute their own host. See [AI Coding Tools](/integrations/ai-tools) for the full reference. Claude Code has native OpenTelemetry support. Add to a developer's shell profile (or ship the equivalent `env` block via MDM managed settings for a whole fleet): ```bash theme={null} export CLAUDE_CODE_ENABLE_TELEMETRY="1" export OTEL_METRICS_EXPORTER="otlp" export OTEL_LOGS_EXPORTER="otlp" export OTEL_EXPORTER_OTLP_PROTOCOL="http/protobuf" export OTEL_EXPORTER_OTLP_ENDPOINT="https://app.navigara.com/api/otlp" export OTEL_EXPORTER_OTLP_HEADERS="Authorization=Bearer " ``` On Claude.ai (Team / Enterprise) sign-in, the developer's email is emitted natively. Under API-key / Bedrock / Vertex auth, also set `OTEL_RESOURCE_ATTRIBUTES="enduser.id=$(git config user.email)"` so usage is attributed to the right person. Copilot CLI telemetry is off by default and is configured through environment variables. Add to a shared profile (e.g. `/etc/profile.d/`) or a `copilot` launcher wrapper: ```bash theme={null} export COPILOT_OTEL_ENABLED="true" export OTEL_EXPORTER_OTLP_ENDPOINT="https://app.navigara.com/api/otlp" export OTEL_EXPORTER_OTLP_PROTOCOL="http/json" export OTEL_EXPORTER_OTLP_HEADERS="Authorization=Bearer " # Copilot emits no identity — enduser.id is how usage is attributed, matched by email. export OTEL_RESOURCE_ATTRIBUTES="enduser.id=$(git config user.email)" ``` Codex configures OTLP through `~/.codex/config.toml` (telemetry off by default): ```toml theme={null} # ~/.codex/config.toml [otel.metrics_exporter.otlp-http] endpoint = "https://app.navigara.com/api/otlp/v1/metrics" protocol = "binary" headers = { Authorization = "Bearer " } [otel.exporter.otlp-http] endpoint = "https://app.navigara.com/api/otlp/v1/logs" protocol = "binary" headers = { Authorization = "Bearer " } ``` Codex metrics carry no identity, so set it per workstation in the shell profile: ```bash theme={null} export OTEL_RESOURCE_ATTRIBUTES="enduser.id=$(git config user.email)" ``` Run one proxy in front of your providers and capture usage for everything routed through it. Requires LiteLLM ≥ 1.89. Enable the OTel callback in `config.yaml`: ```yaml theme={null} litellm_settings: callbacks: ["otel"] ``` Then set on the proxy deployment: ```bash theme={null} export LITELLM_OTEL_INTEGRATION_ENABLE_METRICS="true" export OTEL_EXPORTER="otlp_http" export OTEL_EXPORTER_OTLP_ENDPOINT="https://app.navigara.com/api/otlp" export OTEL_HEADERS="Authorization=Bearer " ``` Attribute usage to developers with per-user virtual keys, JWT/OIDC SSO, or the OpenAI-compatible `user` request field — see [AI Coding Tools → LiteLLM](/integrations/ai-tools#litellm). ## 6. Add your first repository Go to **Repositories > Add Repository**, select your connected provider, and choose the repository to analyze. Navigara will begin processing commits automatically. ## 7. View results Once analysis completes, explore the dashboard to see: * **Performance scores** for individual contributors * **Alignment scores** correlating commits with tasks * **AI-powered commit summaries** and knowledge graphs # Security Best Practices Source: https://docs.navigara.com/security/best-practices Harden a Navigara deployment: network boundaries, identity, secrets, credentials, data protection, and audit logging. This guide tells you how to deploy and operate Navigara securely. It is written for the engineer who owns the deployment. Each section covers one part of the system. Start with the [hardening checklist](#hardening-checklist) and follow the links. This guide covers your responsibilities as the operator. For what each deployment model puts in your infrastructure, see [Deployment overview](/deployment/overview). ## How we secure our own platform Navigara runs an information security management system designed to conform to ISO/IEC 27001:2022, and aligned to SOC 2 and DORA. The recommendations on this page come from the same internal policies. In summary, our policies require: * **Encryption everywhere.** TLS 1.2 or higher for data in transit, AES-256 or equivalent at rest — including backups. MD5, SHA-1, and DES are not permitted. * **Identity as the perimeter.** Unique named identities, single sign-on, and multi-factor authentication on all administrative access. * **Least privilege, with evidence.** Access granted by role and business need, reviewed at least quarterly, and revoked the same business day when someone leaves. * **Secrets never in code.** Credentials live in a secret manager and are injected at run time. A committed secret is handled as a security incident. * **Nothing reaches production unreviewed.** Protected branches, an independent reviewer on every change, and automated deployment from the default branch only. * **Continuous scanning with fixed clocks.** Static analysis, dependency scanning, and image scanning on every change, with remediation targets of 15 days for critical findings, 30 for high, 60 for medium, and 90 for low. An independent penetration test at least annually. * **Tested resilience.** Encrypted backups with validated restores, infrastructure defined as code, and recovery testing at least annually. Navigara is not ISO 27001 certified. The management system is designed to conform to the standard. Contact your account representative for our current policy set, security documentation, or a data processing agreement. ## Hardening checklist Work through this list before you put a deployment into production. "Regulated" marks controls we consider mandatory in banking, insurance, and other regulated environments. | Control | Applies to | Section | | ------------------------------------------------------------------------- | ---------- | ----------------------------------------------------------------------- | | Verify the signature and provenance of every image before you deploy it | All | [Image supply chain](#image-supply-chain) | | Pin every image by digest, not by version tag | All | [Image supply chain](#image-supply-chain) | | Keep the containment defaults: non-root, read-only, no capabilities | All | [Container runtime](#container-runtime) | | Keep the collector on a private network with no inbound ports | All | [Collector hardening](#collector-hardening) | | Terminate TLS at the reverse proxy and keep the security headers | All | [Network boundaries](#network-boundaries) | | Block `/api/metrics` and debug routes at the proxy | All | [Network boundaries](#network-boundaries) | | Restrict the root login endpoint to administrator source ranges | Regulated | [Root admin access](#root-admin-access) | | Decide whether Navigara support access is permitted, and enforce it | Regulated | [Navigara support access](#navigara-support-access) | | Set `TRUSTED_PROXY_CIDRS` when you run behind a load balancer | All | [Network boundaries](#network-boundaries) | | Use single sign-on and leave password authentication off | All | [Identity and access](#identity-and-access) | | Store the root private key in a vault or hardware token | All | [Root admin access](#root-admin-access) | | Attach the narrowest available role to every API token, and set an expiry | All | [API tokens](#api-tokens) | | Hold every secret in a secret manager, injected at run time | All | [Secrets management](#secrets-management) | | Generate a unique random `COLLECTOR_API_KEY` | All | [Secrets management](#secrets-management) | | Use the GitHub App or end-to-end encrypted tokens for Git access | All | [Git and issue-tracker credentials](#git-and-issue-tracker-credentials) | | Grant provider tokens the minimum scopes, read-only where possible | All | [Git and issue-tracker credentials](#git-and-issue-tracker-credentials) | | Encrypt the database at rest and require TLS to it | All | [Database hardening](#database-hardening) | | Run the application as a least-privilege database user | All | [Database hardening](#database-hardening) | | Encrypt the collector work directory at rest | Regulated | [Collector hardening](#collector-hardening) | | Choose an LLM endpoint that matches your data residency rules | Regulated | [What leaves your network](#what-leaves-your-network) | | Ship audit logs to a SIEM and alert on privileged events | Regulated | [Logging, audit, and monitoring](#logging-audit-and-monitoring) | | Set retention for every data class you enable | Regulated | [Personal data and GDPR](#personal-data-and-gdpr) | | Encrypt backups and test a restore | All | [Backup and recovery](#backup-and-recovery) | | Patch on a defined schedule, and know the emergency clock | All | [Updates and patching](#updates-and-patching) | ### Which controls apply to your deployment model | Area | Cloud SaaS | Cloud SaaS + on-prem collector | Full on-premises | | --------------------------------- | ---------- | ------------------------------ | ---------------- | | Reverse proxy, TLS, and headers | Navigara | Navigara | **You** | | Database hardening and backups | Navigara | Navigara | **You** | | Root admin key custody | Navigara | Navigara | **You** | | Collector host and network | Navigara | **You** | **You** | | Git and tracker credential scopes | **You** | **You** | **You** | | Identity provider and SSO policy | **You** | **You** | **You** | | API token lifecycle | **You** | **You** | **You** | | LLM endpoint choice and residency | Navigara | **You** | **You** | ## Image supply chain A container registry proves that the bytes you pulled match the digest you asked for. It does not prove who produced them. **Verify before you deploy.** Navigara signs every released image with [cosign](https://docs.sigstore.dev/) and publishes an SBOM and build provenance alongside it. The signature binds the digest to Navigara's release pipeline. The commands are in [Full on-premises → Verify the release](/deployment/full-on-premises#2-verify-the-release). **Pin by digest.** Set `BACKEND_IMAGE`, `COLLECTOR_IMAGE`, and `FRONTEND_IMAGE` to `:@sha256:`. Pin your third-party images, such as Caddy, the same way. **Scan what you are about to run.** The published SBOM lists every package inside each image. Assess a release against your own vulnerability policy before it reaches production. **Mirror deliberately.** Regulated environments should copy the verified digests into their own registry and deploy from the mirror. Verify *before* you mirror. If `cosign verify` fails, do not deploy the image. Either the version predates image signing, or the image is not the one Navigara published. Contact support before you continue. ## Container runtime The reference deployment ships with containment on by default. Keep it on. | Control | What it does | | -------------------------------------------------- | ----------------------------------------------------------------------------------------- | | `user 1001` (non-root) | The container process is not root | | `read_only: true` | The root filesystem rejects writes | | `cap_drop: ALL` | No Linux capabilities. Caddy keeps `CAP_NET_BIND_SERVICE` alone, to bind ports 80 and 443 | | `no-new-privileges` | A setuid binary inside the image cannot raise privileges | | CPU, memory and PID limits | One runaway component cannot starve the host or the others | | Separate edge, application, and collector networks | The collector cannot reach the proxy or the frontend | Confirm all of this on a running deployment with the checks in [Full on-premises → Start Navigara](/deployment/full-on-premises#8-start-navigara). If a component fails to start with a read-only filesystem error, report it. Add a `tmpfs` mount for that specific path as a temporary measure; do not remove `read_only`. ## Network boundaries Navigara is designed to need **no inbound network access** apart from the user-facing web interface. Keep it that way. **Publish only the reverse proxy.** In the reference deployment, Caddy is the only container that publishes a host port. The backend, frontend, and collector publish nothing at all — they are reachable over the container network, through the proxy. Do not add a `ports:` entry to them: a loopback binding is still reachable by every local process and by anything that can open an SSH tunnel to the host. **Keep the instance off the public internet where you can.** Publish it on an internal network, or behind your VPN or zero-trust proxy. Users reach it the same way they reach your other internal tools. **Block the operational routes at the proxy.** The backend serves Prometheus metrics at `/metrics` and, when explicitly enabled, profiling at `/debug/pprof/`. Neither requires authentication, so neither should be reachable from the internet. Add this to your Caddyfile inside the site block, before the `handle_path /api/*` block: ``` handle /api/metrics { respond 404 } handle /api/debug/* { respond 404 } ``` Scrape metrics from a container attached to the `navigara-edge` network, on `backend:8080/metrics`. The backend publishes no host port. **Keep the security headers.** The reference Caddyfile in [Full on-premises](/deployment/full-on-premises#7-configure-reverse-proxy-caddy) sets HSTS, `X-Frame-Options`, `X-Content-Type-Options`, and `Referrer-Policy`. Add `Permissions-Policy` if your baseline requires it. Do not relax `Access-Control-Allow-Origin` beyond your own domain. **Declare your proxy ranges.** Navigara reads the client IP from `X-Forwarded-For` only when the immediate peer is a trusted proxy. Without this, audit logs and rate limits record your load balancer instead of the real client. `TRUSTED_PROXY_CIDRS` **replaces** the default private ranges — it does not extend them. If you set it, include the Docker bridge range as well, or the reverse proxy and frontend stop being trusted hops: ```bash theme={null} TRUSTED_PROXY_CIDRS=10.20.0.0/16,172.16.0.0/12 ``` **Keep the rate limits on.** Requests without credentials are limited per client IP, and authenticated requests per token. The defaults suit a single instance. Limits count per process, so the effective budget is the limit times the number of backend replicas. Lower the values if you run more than one. | Variable | Default | Purpose | | ---------------------------------------- | ------- | --------------------------------------------------------------------------------------- | | `RATE_LIMIT_IP_PER_MIN` | `100` | Unauthenticated requests per client IP — login, password reset, OAuth start, root login | | `RATE_LIMIT_KEY_PER_MIN` | `1000` | Requests per session token or API token | | `RATE_LIMIT_LOGIN_ATTEMPTS_PER_EMAIL` | `10` | Sign-in attempts per email address | | `RATE_LIMIT_LOGIN_ATTEMPTS_EMAIL_WINDOW` | `15m` | Window for the attempt counter | **Control outbound traffic too.** Navigara needs a small, fixed set of destinations. Allow those and deny the rest — see [What leaves your network](#what-leaves-your-network). ## Identity and access **Use single sign-on.** Connect Google or Microsoft Entra ID so that your identity provider enforces multi-factor authentication, conditional access, and offboarding. Configuration is in [Integrations → Authentication](/integrations/overview#authentication). **Leave password authentication off.** `ENABLE_PASSWORD_AUTH` is `false` by default. Keep it that way unless you have no identity provider. If you do enable password authentication, you must also set `PASSWORD_HASH_PEPPER` to a random secret of **at least 32 bytes**. The backend refuses to start without it. ```bash theme={null} PASSWORD_HASH_PEPPER=$(openssl rand -base64 48) ``` This value cannot be rotated. Changing it invalidates every stored password, and every user must reset. Generate it once, and store it with your other secrets. **Keep the on-premises signup brake.** `DEPLOYMENT_MODE` defaults to `onprem`. In this mode a person who authenticates through your identity provider but belongs to no organization is rejected and no organization is created for them. Access still requires an explicit invitation. Do not change this on a deployment reachable by a wide identity pool. **Assign the smallest role that works.** Navigara separates platform roles from organization roles. | Role | Grants | | -------- | ----------------------------------------------------------------------------------------------- | | `owner` | Full control of the organization, including deletion and ownership transfer | | `admin` | Everything except organization deletion, ownership transfer, and reading AI tool prompt content | | `member` | Read access, plus maintaining contributor and team metadata | | `viewer` | Read-only access | Grant `owner` to no more than two people. Review the member list and the token list at least quarterly, and remove anyone who no longer needs access. **Sessions last seven days.** Sign-out deletes the session immediately, and changing a password ends every other session for that user. Rely on your identity provider for shorter-lived control. SCIM provisioning synchronizes directory identities and attributes so Navigara can attribute work correctly. It does **not** grant organization membership, and de-provisioning a user in your identity provider does not by itself remove their Navigara access. Remove the member in Navigara as part of offboarding. See [SCIM provisioning](/integrations/scim). ## Root admin access Full on-premises deployments have a root administrator that you control with an Ed25519 key pair. The public key goes in `ADMIN_PUBLIC_KEY`; the matching private key signs short-lived, one-time root login credentials. See [Full on-premises → Generate root private key](/deployment/full-on-premises#4-generate-root-private-key). Root bypasses every permission check in every organization. Treat the private key as the most sensitive credential in the deployment. `admin_key.pem` is a root credential. Never commit it, never leave it on the application host, and never share it over chat or email. Do not generate it on the application server. The server only ever needs the public half. Put it in your secret manager, a hardware token, or a password manager with break-glass procedures. Restrict access to named administrators. The reference script signs credentials that expire after 60 seconds and can be spent only once. Keep that window. Sign a credential when you need it, use it immediately, and do not store it. Root login is verified by signature rather than by session, so it accepts requests from anywhere the instance is reachable. In regulated environments, limit it to your administrator networks at the proxy. Two paths reach it and you need both rules — `/impersonate` is the browser's sign-in page, and `/api/v1/auth/impersonate` is the direct API. Add this to your Caddyfile before the `handle_path /api/*` block: ``` @not_admin not remote_ip 10.20.30.0/24 handle /impersonate { route { respond @not_admin 403 reverse_proxy frontend:3000 } } handle /api/v1/auth/impersonate { route { respond @not_admin 403 uri strip_prefix /api reverse_proxy backend:8080 } } ``` If another proxy sits in front of Caddy, use the `client_ip` matcher instead of `remote_ip` so the rule tests the real client rather than the proxy. Every root login writes a log record, and the resulting session is flagged as impersonated. Alert on these — see [Logging, audit, and monitoring](#logging-audit-and-monitoring). Generate a new key pair, replace `ADMIN_PUBLIC_KEY`, and restart the backend. Destroy the old private key. Your key is not the only one this endpoint trusts. Read [Navigara support access](#navigara-support-access) before you sign off on the deployment. ## Navigara support access Every Navigara build contains a Navigara-held public key, and the root login endpoint trusts it **alongside** your `ADMIN_PUBLIC_KEY`. Setting `ADMIN_PUBLIC_KEY` adds your key to the trusted set. It does not replace ours. **What it can do.** A token signed with the matching private key establishes a session as a user on your instance. Your own key is restricted to the `root` account. Ours is not, so it can establish a session as any existing user, and that session reads whatever that user can read. As `root` it bypasses every organization permission check, as described in [Root admin access](#root-admin-access). Assess it as an authentication and data-access path. **What we use it for.** Navigara staff use it to verify changes on instances we operate for a customer. We do not use it to reach instances we do not run for you. This is a statement about how we work, not a technical limit. **What limits it.** * A token is bound to your domain. It carries an audience claim that must match your deployment's own hostname, so a token minted for one instance does not work on another. * Every use is audited **in your logs, not only ours**. The record names the key that was used, who was impersonated, the client address, and the user agent. The resulting session is flagged as impersonated in the database. * Reaching the endpoint requires network access to your instance. If we cannot reach it, we cannot use the key. **You may refuse it.** Two controls stop anybody outside your organization from authenticating to your deployment. Combine them if you want. ### Turn it off in configuration ```bash theme={null} DISABLE_NAVIGARA_SUPPORT_ACCESS=true ``` This drops our key from the trust set at startup. Your `ADMIN_PUBLIC_KEY` becomes the only key that can authenticate as root, and the backend logs the setting at boot so you can confirm it took effect. Licensing is unaffected. With this set, `ADMIN_PUBLIC_KEY` is **required** — the backend refuses to start without it, because otherwise no key could authenticate as root. Make sure you can produce a root login link before you enable it, and keep the private key recoverable. `DISABLE_NAVIGARA_SUPPORT_ACCESS` needs Navigara 0.14.1 or later. On 0.14.0 it has no effect — use the proxy rule below instead. ### Enforce it at the proxy A configuration flag is honored by our software. A proxy rule is enforced by yours. * **Restrict by source.** Allow the endpoint only from your administrator networks, using the rule in [Root admin access](#root-admin-access). Your administrators keep root access. Nobody outside those ranges can reach the endpoint. * **Deny outright.** Return 403 permanently, and lift the rule only when you need root access. This also blocks your own root login. ``` handle /impersonate { respond 403 } handle /api/v1/auth/impersonate { respond 403 } ``` Block **both** paths. The browser sign-in page posts to `/impersonate` and the frontend then calls the backend over the internal Docker network, so a rule on `/api/v1/auth/impersonate` alone does not stop a browser sign-in. Whichever you choose, alert on the audit record so that any use is visible to you — see [Logging, audit, and monitoring](#logging-audit-and-monitoring). If your policy forbids vendor access entirely, tell your account representative. ## API tokens API tokens carry the `navigara_` prefix, are scoped to one organization, and are shown once at creation. Navigara stores only a hash. **Attach the narrowest role available for the job.** Two write-only roles exist for integration tokens: | Purpose | Role to select | Grants | | --------------------------------------------- | ------------------ | ---------------------------------- | | AI coding tool telemetry | Analytics Ingestor | Submitting usage telemetry only | | SCIM provisioning from your identity provider | SCIM Provisioner | Provisioning users and groups only | A token created **without** a role carries broad organization access. The collector requires such a token, so treat `COLLECTOR_API_KEY` as a high-value credential. Give it its own token, never reuse it, restrict who can read it, and rotate it on a schedule. Rules to apply: * **One token per purpose.** Separate the collector, AI tool ingestion, SCIM, and any scripts. A leak then affects one integration. * **Set an expiry.** Tokens do not expire by default. Give each one a date and diarize the renewal. * **Rotate by replacement.** Create the new token, move the consumer over, confirm it works, then delete the old one. * **Revoke on offboarding and on suspicion.** Deleting a token takes effect immediately. * **Never put a token in a URL, a ticket, or a chat message.** Deliver it through your secret manager. ## Secrets management Hold every secret in a secret manager — HashiCorp Vault, AWS Secrets Manager, Google Secret Manager, or Azure Key Vault — and inject it at run time. Do not commit secrets to source control, and do not bake them into images. For the reference Docker Compose deployment, render one secret file per service from your secret manager at deploy time. Create `secrets/backend.env` and `secrets/collector.env` with mode `0600`. Do not create a frontend secret file. ```bash theme={null} install -d -m 0700 /opt/navigara/secrets install -m 0600 /dev/null /opt/navigara/secrets/backend.env install -m 0600 /dev/null /opt/navigara/secrets/collector.env ``` The service matrix is the minimum allowed distribution. Do not add a value to another service without a documented runtime need. | Value | Backend | Collector | Frontend | What it unlocks | | ------------------------------------- | ---------------------------------------- | ------------------------------------ | -------- | --------------------------------------------------------- | | `DATABASE_URL` | Yes | No | No | All application data | | `COLLECTOR_API_KEY` | Yes | Yes | No | The collector's connection to the backend | | `LICENSE_KEY` | Yes | No | No | Analysis features | | `LLM_API_KEY` | Only when backend LLM features need it | Yes when collector analysis needs it | No | Your LLM provider account | | Workload identity configuration | Only when backend uses Vertex AI | Only when collector uses Vertex AI | No | Vertex AI access | | `COLLECTOR_PRIVATE_KEY_PATH` / `_PEM` | No | Only for encrypted Git tokens | No | Decryption of encrypted Git tokens | | `PASSWORD_HASH_PEPPER` | Only with password authentication | No | No | Password hash strength | | `PAGINATION_TOKEN_SECRET` | Yes | No | No | Pagination-token integrity | | `SMTP_PASSWORD` | Only when SMTP authentication is enabled | No | No | Your mail relay | | OAuth client secrets | Only for the enabled provider | No | No | Sign-on and connection flows | | `admin_key.pem` | No. Hold offline. | No | No | Root access — see [Root admin access](#root-admin-access) | Generate `COLLECTOR_API_KEY` and `PAGINATION_TOKEN_SECRET` in your secret manager. Do not use literal values in shell commands or shell history. The production backend must refuse to start when `PAGINATION_TOKEN_SECRET` is absent. Rotate every secret on a defined schedule, and immediately if you suspect exposure. `PASSWORD_HASH_PEPPER` is the exception — it cannot be rotated without resetting every password. ## Git and issue-tracker credentials Navigara reads your repositories and trackers with credentials you supply. These are usually the highest-value credentials in the integration, so scope them tightly. **Prefer the GitHub App.** For GitHub, the Navigara GitHub App issues short-lived installation tokens, scoped to the repositories you select. There is no long-lived token to store or rotate. See [On-prem collector → Git provider authentication](/deployment/on-prem-collector#git-provider-authentication). **Encrypt tokens end to end.** When you run your own collector, encrypt each personal access token against the collector's public key. Navigara stores only the ciphertext and can never read the token; the collector decrypts it in memory when it authenticates to the Git host. See [Encrypted Git tokens](/deployment/encrypted-git-tokens). **Grant read-only, minimum scopes.** Navigara never writes to your repositories or trackers. The required scopes for each provider are listed in [Integrations overview](/integrations/overview). Use a dedicated service account rather than a personal account, so access survives staff changes and is auditable. **Rotate on a schedule.** Mint the new token, encrypt it, paste it in, confirm a successful sync, then revoke the old one. The collector accepts multiple decryption keys at once, so key rotation needs no downtime — see [Key rotation](/deployment/encrypted-git-tokens#key-rotation). **Revoke on offboarding.** If a departing engineer's account issued a token, revoke it the same day. ## Collector hardening The collector clones repositories, runs analysis, and streams results to the backend. It handles source code. Give it the same care as a build agent. **It needs no inbound ports.** The collector always dials out to the backend and holds the connection open. Do not publish any port for it. Its operations endpoint is off entirely unless you set `OPS_PORT`, and when you do it binds to `127.0.0.1` (`OPS_BIND_ADDR`). Widen that only if a scraper must reach it across the network, and restrict who can. **Put it on a private network.** Place it in a private subnet with egress to your Git host, your tracker, your LLM endpoint, and the Navigara backend. Nothing else needs to reach it. **Turn TLS on whenever it leaves the host.** `COLLECTOR_TLS` is only safe as `false` when the collector and backend share one host and one Docker bridge, as in the all-in-one deployment. The moment the collector moves to its own machine, set it: ```bash theme={null} COLLECTOR_TLS=true ``` With `COLLECTOR_TLS=false` across a network, the collector's API key and its analysis payloads travel unencrypted. **Encrypt the work directory.** The collector writes full Git clones to `WORK_DIR` (default `/tmp/git-analysis`), and Git stores the credential for the remote inside each clone. Put `WORK_DIR` on an encrypted volume, and treat the host as one that holds source code and credentials. **Understand the cache setting.** By default the collector deletes each clone after it finishes. Setting `COLLECTOR_CACHE_REPOS=true` keeps clones on disk to speed up later runs — which also means source code and credentials persist between jobs. Enable it only on an encrypted, access-controlled volume, and monitor disk usage. **Keep the provider guards closed.** Two settings widen what a collector may reach. Both default to `false`. | Variable | Default | Notes | | ------------------------------ | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `ALLOW_PRIVATE_PROVIDER_HOSTS` | `false` | Set to `true` only on a **dedicated** collector, and only to reach a self-hosted GitLab, GitHub Enterprise, Bitbucket Data Center, or Jira Data Center on a private address. Cloud metadata and loopback addresses stay blocked either way. | | `ALLOW_LOCAL_REPOSITORIES` | `false` | Permits `file://` repository paths. Leave off in production — it allows reads from the collector's own filesystem. | **Run one collector per trust boundary.** If two parts of your organization must not see each other's code, give them separate collectors with separate credentials rather than one shared collector. **Restrict the host.** Run the containers as an unprivileged user, keep the base OS patched, and limit shell access to the platform team. ## Database hardening PostgreSQL holds everything: analysis results, connection credentials, and user records. It is the highest-value asset in the deployment. * **Encrypt at rest.** Enable storage encryption on your managed instance, or full-disk encryption if you run it yourself. Use AES-256 or equivalent. * **Require TLS.** Keep `sslmode=require` in `DATABASE_URL`. Use `verify-full` with a pinned certificate authority where your baseline calls for it. * **Use a least-privilege application user.** Follow the grants in [Full on-premises → Configure PostgreSQL](/deployment/full-on-premises#6-configure-postgresql). Never point `DATABASE_URL` at a superuser. * **Restrict the network path.** Allow connections only from the application host's address. Never expose port 5432 to the internet. * **Separate administrative access.** Give database administrators their own named accounts, ideally through your cloud provider's identity-based authentication rather than a shared password. * **Audit access.** Log connections and administrative statements, and ship them to the same place as your other audit logs. ## What leaves your network Navigara makes a small, fixed set of outbound connections. Allow these and deny the rest. | Destination | Component | Purpose | Required | | ---------------------- | ------------------ | ------------------------------- | ----------------------------- | | Your Git host | Collector | Cloning and pull request data | Yes | | Your issue tracker | Collector | Alignment scoring | Only with a tracker connected | | Your LLM endpoint | Collector, backend | Commit analysis and summaries | Yes | | PostgreSQL | Backend | All state | Yes | | Your SMTP relay | Backend | Invitations and password resets | Only with email enabled | | Your identity provider | Backend | Single sign-on | Only with SSO enabled | | `app.navigara.com:443` | Collector | Work assignment | Hybrid deployments only | A full on-premises deployment makes **no connection to Navigara**. License keys are verified offline, and there is no automatic update or telemetry channel. ### The LLM endpoint is a processor Commit analysis sends commit messages and the changed lines of code to the LLM endpoint that **you** configure. This is the one path on which code content leaves the deployment, and it goes to your provider, not to Navigara. If your policy requires that source code never leaves your network, host the model inside your network. Any OpenAI-compatible endpoint works, including vLLM and Ollama — see [Full on-premises → LLM API endpoint](/deployment/full-on-premises#llm-api-endpoint). For regulated deployments that use a hosted model: * Choose a **region** that matches your data residency obligations. * Choose an endpoint with **zero data retention** and no training on your inputs, and get it in writing. * Record the provider as a **sub-processor** in your record of processing, and put a data processing agreement in place. ### Telemetry is off by default A self-hosted deployment sends no telemetry unless you configure it. Leave these unset: | Variable | Effect when set | | ------------------------------------ | ----------------------------------------------------------- | | `DD_TRACE_ENABLED` | Sends application traces to a Datadog agent | | `DD_LLMOBS_ENABLED` | Sends **full analysis prompts, including code**, to Datadog | | `NEXT_PUBLIC_DATADOG_APPLICATION_ID` | Enables browser session recording | | `NEXT_PUBLIC_GTM_ID` | Loads Google Tag Manager in the browser | Never enable `DD_LLMOBS_ENABLED` on a deployment that analyzes confidential code. It ships the analysis prompt, including diff content, to a third party. ## Personal data and GDPR Navigara does not process your customers' data. It does process **personal data about your employees and contractors**, so GDPR applies. Plan for it before you go live. ### What Navigara holds | Category | Examples | Source | | ----------------------------- | -------------------------------------------------------------------- | ---------------------- | | Account identity | Name, email address, sign-in provider | Your identity provider | | Git identity | Author name, author email, all merged aliases, provider username | Your repositories | | Directory attributes | Job title, department, manager, when SCIM is enabled | Your identity provider | | Activity | Commit messages, changed lines, pull request titles, review comments | Your repositories | | Tracker content | Issue titles and descriptions | Your issue tracker | | AI tool usage | Which tools an engineer used and how much | Your AI coding tools | | Derived metrics and summaries | Per-person performance figures and narrative summaries | Generated by Navigara | ### Your obligations as controller In a self-hosted deployment you are the **controller** for this data and Navigara is not a processor at all — the data never reaches us. In Cloud SaaS and hybrid deployments Navigara acts as a **processor** on your instructions, under a data processing agreement. Either way, plan the following: Add Navigara to your record of processing activities. Identify your lawful basis — legitimate interest is the usual basis for engineering delivery analytics, and it requires a balancing test you can show. Monitoring must be disclosed. State what is measured, why, and who can see it. Analytics about individual performance usually warrants a data protection impact assessment. Do it before rollout, not after. In several jurisdictions, works councils or employee representatives must be consulted before performance-related monitoring begins. Your LLM provider receives commit content. Your hosting provider holds the database. Both belong in your record, with agreements in place. ### Minimize what you collect * **Analyze only the repositories you need.** Every repository you add widens the data set. * **Leave AI prompt capture off.** `TOOL_USAGE_EVENTS_CAPTURE` is `false` by default. It records prompt and tool content, which is rarely necessary and greatly increases sensitivity. * **Restrict who can read prompt content.** Only organization owners hold that permission. Do not widen it. * **Keep exports controlled.** Reports and summaries name individuals. Treat them as confidential. ### Set retention Retention is configured per data class. Set every value deliberately. | Variable | Default | Controls | | ----------------------------- | ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | | `TOOL_USAGE_RETENTION` | `336h` (14 days) | Raw AI tool usage records. `0` keeps them indefinitely. | | `TOOL_USAGE_EVENTS_RETENTION` | unset | Detailed AI tool events, which may include prompt content. **Unset means these are kept indefinitely** — always set a value if you enable capture. | | `WEBHOOK_EVENT_RETENTION` | `2160h` (90 days) | Raw payloads received from your Git provider. | Expired sessions and password-reset tokens are removed automatically every day. Analysis records are keyed to Git identities rather than to user accounts, so removing a person's login does not remove the commit history attributed to them. Deleting an organization removes its analysis data. Plan how you will answer an erasure or access request before you go live — contact Navigara support to scope the procedure for your deployment. ## Logging, audit, and monitoring **Keep the audit log on.** `AUDIT_LOG_ENABLED` defaults to `true`. It writes one structured record per privileged operation, containing who acted, what they did, which resource, the outcome, and the client address. Request bodies are never logged. **Ship logs off the host.** Forward container logs to your SIEM or log platform, and apply your standard retention there. Logs held only on the application host are lost when it is rebuilt. **Alert on these events:** | Event | Why it matters | | ----------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- | | Root login or Navigara support access (`user impersonated`) | Highest-privilege access to the instance. The record names which key was used, so you can tell the two apart. | | Repeated sign-in failures for one account | Credential attack | | API token created or deleted | New long-lived access path | | Role granted, especially `owner` | Privilege escalation | | Connection created or deleted | Change to what Navigara can read | | Organization deleted | Irreversible data loss | | Rate-limit rejections in volume | Automated probing | **Make client addresses trustworthy.** Configure your edge proxy to overwrite inbound `X-Forwarded-For`, and set `TRUSTED_PROXY_CIDRS` — otherwise a client can put any address in the audit trail. **Watch availability too.** The backend exposes `GET /health`. The collector exposes `/health` and `/health/ready`, but only if you set `OPS_PORT`. A collector that stops connecting means analysis has stopped silently. ## Backup and recovery * **Back up the database on a schedule** that meets your recovery point objective. See [Full on-premises → Backup and restore](/deployment/full-on-premises#backup-and-restore). * **Encrypt the backups** with AES-256 or equivalent, and store them separately from the database. * **Restrict access** to backups as tightly as to the database itself. A backup is a complete copy of every credential and record. * **Test a restore at least annually**, into an isolated environment, and record the result. * **Record your own secrets.** The database alone will not restore a deployment. You also need `.env`, the collector private key, and the root admin key. Keep those in your secret manager, backed up independently. * **Define your objectives.** Navigara targets 24 hours for both recovery time and recovery point. Set yours to match your own requirements. ## Updates and patching * **Pin a digest, not a tag.** See [Image supply chain](#image-supply-chain). * **Mirror the images.** Regulated environments should pull Navigara images into their own registry, scan them there, and deploy from the mirror. Verify the signature before you mirror, then point `BACKEND_IMAGE`, `COLLECTOR_IMAGE`, and `FRONTEND_IMAGE` at it. * **Patch on a clock.** Apply our remediation targets, or your own if they are stricter: 15 days for critical findings, 30 for high, 60 for medium, 90 for low. * **Know the emergency clock.** Active exploitation and Navigara credential compromise do not wait for that schedule. We publish within 48 and 24 hours respectively, and notify your technical contact directly. See [Full on-premises → Emergency security releases](/deployment/full-on-premises#emergency-security-releases). * **Track releases.** Watch the [changelog](/changelog) for security-relevant changes. There is no automatic update — you decide when to upgrade. * **Back up before upgrading.** Database migrations run automatically on startup. * **Patch the host too.** The base operating system, Docker, PostgreSQL, and the reverse proxy are yours to keep current. ## Security configuration reference Every security-relevant setting, in one place. | Variable | Default | Recommendation | | ------------------------------------- | -------------- | ----------------------------------------------------------------------------------------------------------------------------------- | | `ENABLE_PASSWORD_AUTH` | `false` | Leave off. Use single sign-on. | | `PASSWORD_HASH_PEPPER` | — | Required, 32 bytes or more, only with password auth. Not rotatable. | | `DEPLOYMENT_MODE` | `onprem` | Leave as is. Blocks self-signup from reaching data. | | `ADMIN_PUBLIC_KEY` | — | Set it. Keep the private half in a vault. Required when support access is disabled. | | `DISABLE_NAVIGARA_SUPPORT_ACCESS` | `false` | Set to `true` to make `ADMIN_PUBLIC_KEY` the only root credential. See [Navigara support access](#navigara-support-access). | | `COLLECTOR_API_KEY` | — | Generate a unique random value. | | `COLLECTOR_TLS` | `false` | Set to `true` whenever the collector is not on the backend's host. | | `COLLECTOR_CACHE_REPOS` | `false` | Enable only on an encrypted volume. | | `COLLECTOR_PRIVATE_KEY_PATH` | — | Set it to use end-to-end encrypted Git tokens. | | `ALLOW_PRIVATE_PROVIDER_HOSTS` | `false` | Enable only on a dedicated collector reaching a self-hosted provider. | | `ALLOW_LOCAL_REPOSITORIES` | `false` | Leave off in production. | | `ALLOW_HTTP_PROVIDERS` | `false` | Leave off. Development only. | | `TRUSTED_PROXY_CIDRS` | private ranges | Set behind a load balancer. Include the Docker bridge range. | | `ALLOWED_FRONTEND_ORIGINS` | — | Leave empty. It widens where sign-in may redirect; add an origin only if you deliberately serve the interface from a second domain. | | `RATE_LIMIT_IP_PER_MIN` | `100` | Lower it if you run several backend replicas. | | `RATE_LIMIT_KEY_PER_MIN` | `1000` | Lower it if you run several backend replicas. | | `RATE_LIMIT_LOGIN_ATTEMPTS_PER_EMAIL` | `10` | Keep or lower. | | `AUDIT_LOG_ENABLED` | `true` | Leave on. | | `ENABLE_PPROF` | `false` | Leave off in production. | | `ENABLE_GRPC_REFLECTION` | `false` | Leave off in production. | | `TOOL_USAGE_EVENTS_CAPTURE` | `false` | Leave off unless you need prompt content. | | `TOOL_USAGE_EVENTS_RETENTION` | unset | Set a value if you enable capture. | | `TOOL_USAGE_RETENTION` | `336h` | Set to match your retention policy. | | `WEBHOOK_EVENT_RETENTION` | `2160h` | Set to match your retention policy. | | `DD_TRACE_ENABLED` | `false` | Leave off unless you run Datadog yourself. | | `DD_LLMOBS_ENABLED` | `false` | Leave off. It sends code to a third party. | | `DATABASE_URL` | — | Use a least-privilege user and `sslmode=require`. | | `SMTP_TLS` | `starttls` | Keep TLS on. Do not use `none`. | ## Reporting a security issue If you find a security problem in Navigara, email [support@navigara.com](mailto:support@navigara.com) with the details and a way to reach you. Please report it to us before disclosing it publicly. We will confirm receipt, keep you updated, and credit you if you would like. For our current security documentation, policy summaries, or a data processing agreement, contact your Navigara account representative.