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

# Integrations

> Set up and configure data source integrations for Bilanc.

Bilanc ingests data from multiple sources to provide engineering metrics and insights.

## Supported Integrations

| Integration      | Qualified domain name | API endpoint                        |
| ---------------- | --------------------- | ----------------------------------- |
| Cursor           | `api.cursor.com`      | `https://api.cursor.com`            |
| Claude Code API  | `api.anthropic.com`   | `https://api.anthropic.com/v1`      |
| Codex Enterprise | `api.chatgpt.com`     | `https://api.chatgpt.com/v1`        |
| Augment          | `api.augmentcode.com` | `https://api.augmentcode.com`       |
| Jira             | `api.atlassian.com`   | `https://api.atlassian.com/ex/jira` |
| Linear           | `api.linear.app`      | `https://api.linear.app`            |
| GitHub           | `api.github.com`      | `https://api.github.com`            |
| GitLab           | `gitlab.com`          | `https://gitlab.com/api/v4`         |
| BitBucket        | `api.bitbucket.org`   | `https://api.bitbucket.org/2.0`     |
| CircleCI         | `circleci.com`        | `https://circleci.com/api/v2/me`    |

***

## GitHub

GitHub is the primary source for code and pull request metrics.

### Create a Personal Access Token

1. Go to [GitHub Settings > Developer Settings > Personal Access Tokens](https://github.com/settings/tokens)
2. Click **Generate new token (classic)**
3. Give it a descriptive name (e.g., "Bilanc Self-Hosted")
4. Select the following scopes:
   * `repo` - Full control of private repositories
   * `read:org` - Read organization membership

<Warning>
  For organization repositories, the token owner must have access to all repositories you want to track.
</Warning>

### Configure Environment Variables

Add to your `.env` file:

```bash theme={null}
GITHUB_ACCESS_TOKEN=ghp_your_token_here
GITHUB_REPOSITORY=owner/repo-1 owner/repo-2 owner/repo-3
```

<Note>
  The `GITHUB_REPOSITORY` variable accepts a **space-separated** list of repositories in `owner/name` format.
</Note>

### Configure the Tap

Add GitHub to your `tenant_config.yaml`:

```yaml theme={null}
taps:
  - name: github
    type: tap-github
    config:
      start_date: 2025-01-01
      repository: !ENV ${GITHUB_REPOSITORY}
```

### GitHub Metrics Collected

* Pull requests (opened, merged, closed, review times)
* Commits and commit frequency
* Code reviews and review comments
* Releases and deployment frequency
* Repository activity

***

## Linear

Linear provides issue and project management metrics.

### Create an API Token

1. Go to [Linear Settings > API](https://linear.app/settings/api)
2. Click **Create new API key**
3. Give it a descriptive name (e.g., "Bilanc Self-Hosted")
4. Copy the generated token

<Note>
  The API token provides access to all workspaces the user has access to.
</Note>

### Configure Environment Variables

Add to your `.env` file:

```bash theme={null}
LINEAR_ACCESS_TOKEN=lin_api_your_token_here
```

### Configure the Tap

Add Linear to your `tenant_config.yaml`:

```yaml theme={null}
taps:
  - name: linear
    type: tap-linear
    config:
      start_date: 2025-01-01
```

### Linear Metrics Collected

* Issues (created, completed, cycle time)
* Projects and project progress
* Cycles and cycle velocity
* Team workload and distribution

### Disabling Linear

If you don't use Linear, see [Advanced Configuration](/self-hosting/advanced#disabling-linear) for instructions on disabling the integration.

***

## Cursor

Cursor provides AI coding assistant usage metrics.

### Get Your API Key

1. Contact Bilanc support to obtain your Cursor API key
2. The key is specific to your organization

### Configure Environment Variables

Add to your `.env` file:

```bash theme={null}
CURSOR_API_KEY=your_cursor_api_key
```

### Configure the Tap

Add Cursor to your `tenant_config.yaml`:

```yaml theme={null}
taps:
  - name: cursor
    type: tap-cursor
    config:
      start_date: 2025-01-01
```

### Cursor Metrics Collected

* AI completions and suggestions
* Code generation usage
* Time saved by AI assistance
* Adoption rates across teams

***

## Multiple Integrations Example

Here's a complete `tenant_config.yaml` with all integrations enabled:

```yaml theme={null}
tenants:
  - name: Acme Corporation
    domain: acme.com
    is_auto_onboarding_enabled: true
    taps:
      - name: github
        type: tap-github
        config:
          start_date: 2025-01-01
          repository: !ENV ${GITHUB_REPOSITORY}
      
      - name: linear
        type: tap-linear
        config:
          start_date: 2025-01-01
      
      - name: cursor
        type: tap-cursor
        config:
          start_date: 2025-01-01
```

***

## Start Date Configuration

The `start_date` field determines how far back Bilanc fetches historical data:

| Start Date   | Data Volume | Initial Sync Time |
| ------------ | ----------- | ----------------- |
| 30 days ago  | Small       | \~5-10 minutes    |
| 6 months ago | Medium      | \~30-60 minutes   |
| 1+ year ago  | Large       | 1-3 hours         |

<Tip>
  Start with a recent date for initial testing, then adjust to collect more historical data once everything is working.
</Tip>

***

## Verifying Integrations

After configuring integrations:

1. Start or restart Bilanc: `make r`
2. Open the Dagster UI at [http://localhost:4000](http://localhost:4000)
3. Check that the pipelines for each integration are running
4. View the job history to verify data is being ingested

***

## Troubleshooting

### GitHub: 401 Unauthorized

* Verify your token hasn't expired
* Check that the token has the required scopes (`repo`, `read:org`)
* Ensure the token owner has access to the specified repositories

### Linear: No Data

* Verify the API token is correct
* Check that the token owner has access to the workspace
* Ensure there are issues within the `start_date` range

### Cursor: Connection Failed

* Verify the API key is correct
* Contact Bilanc support if issues persist

For more troubleshooting help, see [Troubleshooting](/self-hosting/troubleshooting).