Integrations Setup

ShipLens connects to your source control platform to discover repositories, fetch commits, and receive push notifications for automatic analysis.

Quick Start

1. Connect your GitHub or Bitbucket account from the Integrations page
2. Toggle on the repositories you want to analyze
3. Push code — commits are analyzed automatically via webhooks

That's it. Once connected, new pushes trigger analysis within seconds.

GitHub App

Setup

1. Create a GitHub App at https://github.com/settings/apps/new
2. Set the Webhook URL to https://your-domain.com/webhooks/github
3. Generate a webhook secret (random string — save it)
4. Grant Repository → Contents (read-only) and Repository → Metadata (read-only) permissions
5. Subscribe to the Push event
6. Create the app, then generate a private key (downloads a .pem file)
7. Note the App ID, Client ID, and generate a Client secret

Install

Visit https://github.com/apps/your-app-name/installations/new, select your organization, and choose which repositories to grant access to. GitHub redirects back to ShipLens, which stores the installation and discovers available repos.

Authentication Flow

Install app on GitHub org
    |
    v
GitHub redirects to /github/callback with installation_id
    |
    v
ShipLens signs a JWT with the private key
    |
    v
Exchanges JWT for an installation access token (1-hour TTL)
    |
    v
Discovers repositories via GitHub API

Bitbucket App

Setup

1. Create a Bitbucket Cloud App in the Atlassian Developer Console
2. Set two environment variables: BITBUCKET_APP_KEY and BITBUCKET_BASE_URL
3. ShipLens automatically serves a descriptor at /.atlassian-connect.json — point the Developer Console to this URL
4. The descriptor requests account, repository, and pullrequest scopes

Install

Install the app on your Bitbucket workspace from the Developer Console. Bitbucket calls ShipLens's installed lifecycle endpoint with a clientKey and sharedSecret, which are stored automatically. No static keys to manage.

Authentication Flow

Install app on Bitbucket workspace
    |
    v
Bitbucket POSTs to /webhooks/bitbucket/installed
with clientKey and sharedSecret
    |
    v
ShipLens stores credentials
    |
    v
Generates HS256 JWT for API calls (4-minute TTL)
    |
    v
Discovers repositories via Bitbucket API

Auto-Discovery

Once an integration is installed, ShipLens automatically discovers all repositories the app has access to. Repos appear on the Integrations page but are not analyzed by default — you choose which ones to enable.

Auto-Analysis

When a push event hits an enabled repository, the webhook is verified and an Oban job is enqueued to fetch and analyze the new commits. The analysis pipeline runs the same triage and tiered analysis as described in Commit Analysis.

Repo Toggling

From the Integrations page, toggle repositories on or off at any time. Disabling a repo stops future webhook processing but preserves all existing analysis data. Re-enabling it picks up from where it left off.

Slack Integration

Configure Slack to receive periodic digest summaries for your team. Set the SLACK_WEBHOOK_URL environment variable and enable digest delivery from the team settings page.

Environment Variables

# GitHub
GITHUB_APP_ID=12345
GITHUB_APP_NAME=team-analyzer
GITHUB_PRIVATE_KEY="-----BEGIN RSA PRIVATE KEY-----\n...\n-----END RSA PRIVATE KEY-----"
GITHUB_WEBHOOK_SECRET=random-secret-string
GITHUB_CLIENT_ID=Iv1.abc123
GITHUB_CLIENT_SECRET=abc123...

# Bitbucket
BITBUCKET_APP_KEY=team-analyzer
BITBUCKET_BASE_URL=https://your-domain.com

# Slack (optional)
SLACK_WEBHOOK_URL=https://hooks.slack.com/services/...

# Required for all integrations
ANTHROPIC_API_KEY=sk-ant-...
DATABASE_URL=postgres://user:pass@host/team_analyzer
SECRET_KEY_BASE=...
PHX_HOST=your-domain.com

For full setup details including troubleshooting, see the INTEGRATIONS.md file in the project root.