Linear Integration

The Linear integration allows Tembo to automatically detect and solve issues from your Linear workspace. Once connected, Tembo can respond to issue assignments and label changes to provide AI-powered code solutions.

​

Features

• Automatic Issue Detection: Tembo monitors your Linear workspace for new issues and updates
• AI-Powered Solutions: When issues are assigned to Tembo or labeled with “tembo”, the AI agent analyzes the issue and provides code solutions
• Repository Linking: Connect specific Linear issues to GitHub repositories for targeted solutions
• Webhook Support: Real-time updates through Linear webhooks for immediate response
• Credit Management: Integrated billing system to manage AI solution credits

​

Setup

​

1. OAuth Configuration

The Linear integration uses OAuth 2.0 for secure authentication. Configure the following environment variables:

LINEAR_CLIENT_ID=your_linear_client_id
LINEAR_CLIENT_SECRET=your_linear_client_secret
LINEAR_WEBHOOK_SECRET=your_webhook_secret
LINEAR_API_KEY=your_api_key  # For feature requests

​

2. OAuth Scopes

The integration requires the following Linear API scopes:

• read - Read access to workspace data
• write - Write access for creating comments and updating issues
• app:assignable - Allows the app to be assigned to issues
• app:mentionable - Allows the app to be mentioned in comments

​

3. Webhook Configuration

Configure Linear webhooks to send notifications to:

POST /webhook/linear

Required webhook events:

• Issue updates (label changes, assignments)
• OAuth app revocation

​

Usage

​

Issue Assignment Method

1. Assign any Linear issue to the Tembo app
2. Tembo will automatically:
   • Create a comment confirming the assignment
   • Queue the issue for AI analysis (if credits available)
   • Update the issue status to “In Progress” when solving begins

​

Label Method

1. Add the “tembo” label to any Linear issue
2. Tembo will automatically:
   • Create a comment acknowledging the label
   • Queue the issue for AI analysis (if credits available)

​

Repository Linking

1. Connect GitHub repositories during setup
2. Linear labels are automatically created for each repository
3. Add a repository label to an issue to link it to that specific codebase
4. Tembo will focus solutions on the linked repository

​

Issue Processing

​

Issue States

Tembo syncs with the following Linear workflow states:

• All non-completed and non-canceled states are monitored
• Issues in “completed” or “canceled” states are skipped

​

Priority Mapping

Linear priorities are mapped to Tembo severity levels:

​

Data Structure

Issues are stored with the following structure:

interface LinearIssueData {
	task: string; // Issue title
	description: string; // Issue description
	status: string; // Current workflow state
	data: {
		issue: object; // Full Linear issue object
	};
	context?: object; // Additional context
}

​

Automatic Labels

​

System Labels

Tembo automatically creates the following labels in your Linear workspace:

• “Tembo” - Used to trigger AI solutions (alternative to assignment)
• “Tembo Git Repositories” - Parent group for repository labels

​

Repository Labels

For each connected GitHub repository, Tembo creates:

• A child label under “Tembo Git Repositories”
• Named after the repository
• Linked to the specific codebase for targeted solutions

​

API Endpoints

​

Feature Requests

Create feature requests directly in Linear:

POST /api/linear
Content-Type: application/json

{
  "summary": "Feature title",
  "description": "Detailed description",
  "user": {
    "id": "user_id",
    "name": "User Name",
    "email": "user@example.com"
  }
}

​

Webhook Events

​

Issue Updates

Triggered when:

• Labels are added/removed (especially “tembo” label)
• Repository labels are added
• Issue assignments change

​

Issue Assignments

Triggered when:

• Issues are assigned to the Tembo app
• Automatic comment creation and queuing

​

OAuth Revocation

Triggered when:

• OAuth access is revoked
• Automatic cleanup of integration data

​

Comments and Notifications

Tembo automatically creates comments in Linear for:

​

Assignment/Label Comments

@user I am starting work on this task now! [View issue on Tembo](link)

​

Repository Link Comments

@user I have linked the [repository-name](repo-url) repository to this task.

​

Insufficient Credits

@user Insufficient credits. [Buy credits here](billing-link)

​

Integration Management

​

Sync Process

The integration periodically syncs:

• Workflow states → Issue sources
• Labels → Issue sources
• Repository connections → Label relationships

​

Credit System

• Each AI solution consumes credits
• Credit balance is checked before queuing issues
• Users are notified when credits are insufficient

​

Troubleshooting

​

Common Issues

1. Webhook not receiving events

   • Verify webhook URL is accessible
   • Check webhook secret configuration
   • Ensure required events are enabled

2. OAuth authentication failures

   • Verify client ID and secret
   • Check redirect URI configuration
   • Ensure required scopes are granted

3. Issues not being processed

   • Verify “tembo” label exists
   • Check credit balance
   • Review issue assignment to Tembo app

4. Repository labels not working

   • Ensure GitHub integration is connected
   • Verify repository permissions
   • Check label creation in Linear workspace

​

Debug Information

The integration logs detailed information for troubleshooting:

• Webhook payload processing
• Issue upsert operations
• Credit balance checks
• Label and assignment handling

For additional support, check the application logs for detailed error messages and processing status.