Integrations

Set up and configure data source integrations for Bilanc.

Bilanc ingests data from multiple sources to provide engineering metrics and insights. This guide covers how to set up each integration.

Supported Integrations

Integration	Type	Description
GitHub	tap-github	Pull requests, commits, reviews, releases
Linear	tap-linear	Issues, projects, cycles, team data
Cursor	tap-cursor	AI coding assistant usage metrics

---

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

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

Configure Environment Variables

Add to your .env file:

GITHUB_ACCESS_TOKEN=ghp_your_token_here
GITHUB_REPOSITORY=owner/repo-1 owner/repo-2 owner/repo-3

The GITHUB_REPOSITORY variable accepts a space-separated list of repositories in owner/name format.

Configure the Tap

Add GitHub to your tenant_config.yaml:

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
2. Click Create new API key
3. Give it a descriptive name (e.g., “Bilanc Self-Hosted”)
4. Copy the generated token

The API token provides access to all workspaces the user has access to.

Configure Environment Variables

Add to your .env file:

LINEAR_ACCESS_TOKEN=lin_api_your_token_here

Configure the Tap

Add Linear to your tenant_config.yaml:

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

CURSOR_API_KEY=your_cursor_api_key

Configure the Tap

Add Cursor to your tenant_config.yaml:

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:

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

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

---

Verifying Integrations

After configuring integrations:

1. Start or restart Bilanc: make r
2. Open the Dagster UI at 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.