Linear Integration Setup Guide
Overview
This document provides step-by-step instructions for integrating Linear task management with the ChainAlign development workflow.
Status: Ready for setup Integration Type: GraphQL API (Personal API Key or OAuth) SDKs Available: TypeScript/JavaScript SDK
Quick Start
1. Create Linear Account & Workspace
- Go to linear.app
- Sign up or log in to your workspace
- Create a team for ChainAlign development (e.g., "ChainAlign" or "CA")
- Note your Team Key (e.g., "CA", "ENG") - you'll need this
2. Generate API Key
- Go to Linear Settings → API (or directly to workspace API settings)
- Click Create API key
- Name it: "ChainAlign Development"
- Copy the generated key (save securely)
3. Add to Environment
Backend (.env file):
LINEAR_API_KEY=lin_api_xxxxxxxxxxxxxxxxxxxx
LINEAR_TEAM_KEY=CA
Note: The LINEAR_ENABLED variable is optional. The Linear client will initialize automatically if LINEAR_API_KEY is present.
Configuration
Initialize Linear Client
In your backend application (e.g., server.js):
import { initializeLinear, getLinearClient } from './src/integrations/linearClient.js';
// On server startup
if (process.env.LINEAR_API_KEY) {
try {
initializeLinear(process.env.LINEAR_API_KEY);
console.log('✅ Linear integration initialized');
} catch (error) {
console.warn('⚠️ Linear integration not available:', error.message);
}
}
// Later, use the client
const linear = getLinearClient();
Verify Connection
Use the provided Linear CLI utility to verify your connection:
node tasks/linear_cli.js list
This will:
- ✅ Verify your API key is valid
- ✅ Connect to Linear API
- ✅ List open issues from your team
Additional CLI Commands:
node tasks/linear_cli.js next # Show next 5 high-priority issues
node tasks/linear_cli.js done CA-123 # Mark issue as done
node tasks/linear_cli.js new "Issue title" # Create new issue
Note: The Linear CLI is the recommended way to verify your Linear setup. It includes comprehensive error checking and reporting.
Common Operations
Create a Task/Issue
const linear = getLinearClient();
const issue = await linear.createTaskIssue('CA', {
title: 'Build Scenario Financial Service',
description: 'Implement P&L projection, working capital, cash flow calculations',
priority: 1, // 1 = Urgent, 2 = High, 3 = Medium, 4 = Low
estimate: 40, // Story points (optional)
assigneeEmail: 'pramod@example.com' // (optional)
});
console.log(`Created: ${issue.issue.identifier}`);
// Output: Created: CA-123
Update Issue Status
await linear.updateIssueStatus('CA-123', 'In Progress');
// or
await linear.updateIssueStatus('CA-123', 'Done');
Add Commit Information
When you make git commits, automatically log to Linear:
// After git commit
const linearClient = getLinearClient();
await linearClient.syncCommit('CA-123', {
hash: 'ab1cd23ef',
author: 'Pramod Prasanth',
message: '[M5.3] Build Scenario Financial Service',
filesChanged: 5,
insertions: 800,
deletions: 20
});
Get Issue Details
const issue = await linear.getIssue('CA-123');
console.log(`Status: ${issue.status.name}`);
console.log(`Assigned to: ${issue.assignee?.name}`);
console.log(`Priority: ${issue.priority}`);
Add Comment to Issue
await linear.addComment('CA-123', `
✅ Completed P&L reconciliation checks
- Gross profit validation implemented
- Ratio sanity checks added
- Temporal consistency detection built
See commit: ab1cd23ef
`);
Workflow Integration
Git Hook Integration (Optional)
Create a git hook to automatically link commits to Linear issues:
File: .git/hooks/post-commit (make executable with chmod +x)
#!/bin/bash
# Extract Linear issue from commit message
COMMIT_MSG=$(git log -1 --pretty=%B)
ISSUE_ID=$(echo "$COMMIT_MSG" | grep -oE '[A-Z]+-[0-9]+' | head -1)
if [ ! -z "$ISSUE_ID" ]; then
# Optionally update Linear (requires Node.js script)
echo "Commit linked to $ISSUE_ID"
fi
Commit Message Format
Use this format to link commits to Linear issues:
[CA-123] Build Scenario Financial Service
Implements P&L projection, working capital, cash flow calculations
- P&L reconciliation with tolerance checking
- Working capital impact analysis
- Cash flow statement generation
- Financial ratio calculations
- NPV analysis with configurable discount rates
Technical:
- 800+ lines of service code
- Comprehensive test suite
- Database migration for results storage
Related: CA-124, CA-125
Format:
[ISSUE-ID] Commit title
Description of changes
- Bullet point 1
- Bullet point 2
Related: OTHER-ISSUE-ID
API Reference
Create Issue
const issue = await linear.createIssue('CA', {
title: 'Task title',
description: 'Detailed description',
priority: 1, // 1-4
estimate: 40, // Story points
state: 'backlog', // or 'todo', 'in_progress', etc.
});
Update Issue
await linear.updateIssue('CA-123', {
title: 'New title',
priority: 2,
status: { name: 'In Progress' },
assigneeId: 'user-id' // Get from Linear
});
Fetch Issues
// All team issues
const issues = await linear.getTeamIssues('CA');
// With filters
const issues = await linear.getTeamIssues('CA', {
filter: {
status: { name: { eq: 'In Progress' } }
}
});
Cycles Management
// Get current cycles
const cycles = await linear.getTeamCycles('CA');
// Create issue in cycle
await linear.createIssue('CA', {
title: 'Task',
cycleId: cycles[0].id
});
Team Structure
Suggested Team Setup
Team: "ChainAlign" (Key: "CA")
Sub-teams/Labels (in Linear):
backend- Backend services and APIsfrontend- Frontend pages and componentsguardrails- Guardrails and validationdatabase- Database schemas and migrationsdocumentation- Technical documentation
Cycles (recommended):
- Milestone 1: Foundation (2 weeks)
- Milestone 2: Core Features (2 weeks)
- Milestone 3: Financial Intelligence (2 weeks)
- Milestone 4: Guardrails & QA (2 weeks)
- Sprint N: Continuous improvement
Task Management Examples
M5.3: Complete Example
Parent Issue: CA-100 - Implement Decision Intelligence Features
├── CA-101: Build Scenario Financial Service
│ ├── CA-101a: P&L Projection Model
│ ├── CA-101b: Working Capital Analysis
│ ├── CA-101c: Cash Flow Statement
│ └── CA-101d: Financial Ratios Suite
│
├── CA-102: Implement Guardrails Framework
│ ├── CA-102a: Financial Accuracy Guardrails
│ ├── CA-102b: Scenario Financial Guardrails
│ ├── CA-102c: Language & Content Quality
│ └── CA-102d: RAG Evaluation Service
│
└── CA-103: Build Frontend Pages
├── CA-103a: HomePage (role-based)
├── CA-103b: DemandPlannerPage
├── CA-103c: DemandConsensusPage
└── CA-103d: EnhancedWhatIfWorkbenchPage
Issue Templates
Backend Service Issue:
Title: [Service Name] - [Core Feature]
Description:
- Purpose and requirements
- Key methods/functions
- Data models
- Integration points
- Testing requirements
Estimate: [story points]
Priority: [1-4]
Labels: backend, [domain]
Frontend Page Issue:
Title: [Page Name] - [Feature Description]
Description:
- User flows
- Data sources (API endpoints)
- Components needed
- Accessibility requirements
- Performance targets
Estimate: [story points]
Priority: [1-4]
Labels: frontend, ui
Bug Issue:
Title: [Bug] - [Clear description]
Description:
- Steps to reproduce
- Expected behavior
- Actual behavior
- Screenshots/logs
Priority: [1-4]
Labels: bug, [domain]
Automations (Future)
Webhook Integration
Linear supports webhooks for real-time updates:
// Listen for Linear webhooks
app.post('/api/webhooks/linear', async (req, res) => {
const { type, data } = req.body;
if (type === 'issue.updated') {
const { id, title, status } = data;
console.log(`Issue ${id} status changed to ${status.name}`);
// Trigger your own workflows here
if (status.name === 'Done') {
// Deploy, notify team, etc.
}
}
res.json({ ok: true });
});
To enable:
- Go to Linear workspace settings → Webhooks
- Add webhook URL:
https://your-domain.com/api/webhooks/linear - Select events:
issue.updated,issue.created,comment.created
CI/CD Integration
Update Linear issue status from CI/CD pipeline:
#!/bin/bash
# In your CI/CD pipeline (GitHub Actions, etc.)
ISSUE_ID="CA-123"
STATUS="Done"
curl -X POST https://api.linear.app/graphql \
-H "Authorization: Bearer $LINEAR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"query": "mutation { issueUpdate(id: \"'$ISSUE_ID'\", input: { status: { name: \"'$STATUS'\" } }) { success } }"
}'
Troubleshooting
"Linear client not initialized"
Fix: Call initializeLinear(apiKey) on server startup
"API key invalid"
Fix: Verify LINEAR_API_KEY in .env file matches Linear settings
GraphQL errors
Fix: Check Linear API documentation for correct query syntax
Rate limiting
Fix: Linear allows 60 requests per minute. Add exponential backoff retry logic
Security Best Practices
- Never commit API keys to git
- Use .env files for local development (add to .gitignore)
- Use OAuth for production (instead of personal API keys)
- Rotate keys regularly (monthly recommended)
- Audit webhook signatures if using webhooks
- Log API usage for compliance tracking
Next Steps
- ✅ Create Linear workspace
- ✅ Generate API key
- ✅ Add to
.envfile - ✅ Initialize Linear client in
server.js - ✅ Test connection with
node backend/test-linear.js - ✅ Create your first issue
- ✅ Link commits to Linear issues
- ✅ Set up team structure and cycles
- ✅ Optionally configure webhooks/CI integration
Resources
- Linear Docs: https://linear.app/docs
- Linear API: https://developers.linear.app
- GraphQL Schema: https://linear.app/developers/graphql
- OAuth Setup: https://linear.app/docs/oauth
- SDK Reference: https://linear.app/developers/sdk
Support
For issues with Linear integration:
- Check the troubleshooting section above
- Review Linear API error logs
- Consult Linear documentation
- Contact Linear support: support@linear.app