> ## Documentation Index
> Fetch the complete documentation index at: https://docs.navigara.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Supported Integrations

> 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) |

<Info>
  **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.
</Info>

See the dedicated [AI Coding Tools](/integrations/ai-tools) page for complete, copy-pasteable setup for each tool, the ingest endpoint, and attribution.

<Note>
  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.
</Note>

***

## 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://<your-navigara-host>/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://<your-navigara-host>/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://<your-navigara-host>/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://<your-navigara-host>/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.

<Note>
  SCIM enriches contributor profiles — it does not grant sign-in access. Users still authenticate through SSO or an invite.
</Note>

***

## 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=<bedrock-api-key>
LLM_API_URL=https://bedrock-runtime.<region>.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=<foundry-api-key>
LLM_API_URL=https://<your-resource>.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=<your-deployment-name>
LLM_API_KEY=<azure-api-key>
LLM_API_URL=https://<your-resource>.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=<gateway-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.