Kanban Metrics Collector for Linear

This Ruby script collects kanban metrics from the Linear API, including cycle time, lead time, throughput, and work in progress (WIP).

🤖 AI Code Review

This project uses GitHub Copilot to automatically review all pull requests against our coding standards and design patterns. The AI system checks for:

• Architecture adherence and design patterns
• SOLID principles and Ruby best practices
• Testing quality and security considerations
• Code maintainability and performance

📖 Learn more about our AI Code Review coding standards →

🧪 AI Test Runner

This project includes an AI-powered Test Runner that intelligently selects and runs only the tests relevant to your code changes, reducing CI time while maintaining comprehensive coverage.

Features

• 🧠 AI-Powered Analysis: Uses Claude 3 to analyze code changes and understand test dependencies
• ⚡ Performance Optimization: Runs only relevant tests instead of the entire test suite
• 📊 Detailed Reporting: Provides comprehensive analysis of why tests were selected
• 🔄 Fallback Safety: Falls back to running all tests if AI analysis fails

The AI test runner automatically triggers on all pushes and pull requests, analyzing your changes and running only the necessary tests.

📖 Learn more about the AI Test Runner →

Setup

1. Install Ruby dependencies:

bundle install

2. Create a .env file from the example:

cp config/.env.example config/.env

3. Get your Linear API token from Linear Settings and add it to your .env file:

LINEAR_API_TOKEN=your_actual_token_here

Usage

Run the script to collect metrics:

./bin/kanban_metrics

Options

• --team-id TEAM_ID - Filter by specific team ID
• --start-date YYYY-MM-DD - Start date for metrics collection
• --end-date YYYY-MM-DD - End date for metrics collection
• --format FORMAT - Output format (table, json, csv) - default: table
• --page-size SIZE - Number of issues per page for API pagination (default: 250)
• --no-cache - Disable API response caching (fetch fresh data)
• --team-metrics - Include team-based metrics breakdown (disabled by default)
• --include-archived - Include archived tickets in the analysis (disabled by default)
• --ticket-details - Include individual ticket details in output (disabled by default, works with all formats)

Examples

# Basic usage (overall metrics only)
./bin/kanban_metrics

# Fetch all issues with automatic pagination
./bin/kanban_metrics --page-size 500  # Larger pages for faster fetching

# Include team metrics breakdown
./bin/kanban_metrics --team-metrics

# Filter by team and date range with team metrics
./bin/kanban_metrics --team-id "TEAM123" --start-date "2024-01-01" --end-date "2024-12-31" --team-metrics

# Output as JSON
./bin/kanban_metrics --format json

# Output as CSV with team metrics
./bin/kanban_metrics --format csv --team-metrics

# Output with individual ticket details (available in all formats)
./bin/kanban_metrics --ticket-details                           # Table format with ticket details
./bin/kanban_metrics --format json --ticket-details             # JSON format with ticket details
./bin/kanban_metrics --format csv --ticket-details              # CSV format with ticket details

# Combine team metrics and ticket details
./bin/kanban_metrics --format csv --team-metrics --ticket-details

# Include archived tickets in the analysis
./bin/kanban_metrics --include-archived

# Include archived tickets with team metrics
./bin/kanban_metrics --include-archived --team-metrics

# Filter by date range and include archived tickets
./bin/kanban_metrics --start-date "2024-01-01" --end-date "2024-12-31" --include-archived

Metrics Collected

• Cycle Time: Time from when work starts to when it's completed
• Lead Time: Time from when work is requested to when it's completed
• Throughput: Number of items completed per time period
• Work in Progress (WIP): Number of items currently in progress
• Flow Efficiency: Percentage of time spent on active work vs waiting

Automatic Pagination

The script now supports automatic pagination to fetch all issues from your Linear workspace, not just the first 250. The script will automatically fetch multiple pages until all issues matching your criteria are retrieved.

# Automatically fetches all issues (may be thousands!)
./bin/kanban_metrics

# The script will show pagination progress for large datasets
### 📄 Pagination Support

The script automatically fetches all issues from Linear using pagination. Linear's API has a maximum page size of 250 issues per request:

```bash
# Use default page size (250)
./bin/kanban_metrics

# Custom page size (automatically capped at 250)
./bin/kanban_metrics --page-size 100

# Attempting to use >250 will show a warning and use 250
./bin/kanban_metrics --page-size 1000
# ⚠️  Warning: Linear API maximum page size is 250. Using 250 instead of 1000.

With debug mode enabled, you can see the pagination in action:

DEBUG=true ./bin/kanban_metrics
# 📄 Fetching page 1...
# 📄 Fetching page 2...
# 📄 Fetching page 3...
# ✅ Successfully fetched 5015 total issues from Linear API

👥 Team Metrics (Optional)

By default, the script shows only overall metrics for improved performance and cleaner output. Use the --team-metrics flag to include detailed team breakdowns:

# Show team-specific metrics and comparisons
./bin/kanban_metrics --team-metrics

# Export team metrics as CSV
./bin/kanban_metrics --team-metrics --format csv

Team metrics include per-team cycle time, lead time, throughput, and a comparison table across all teams.

📦 Archived Tickets

By default, the Linear API excludes archived tickets from the results. Use the --include-archived flag to include archived tickets in your analysis:

# Default behavior - excludes archived tickets
./bin/kanban_metrics

# Include archived tickets in the analysis
./bin/kanban_metrics --include-archived

# Include archived tickets with specific date range
./bin/kanban_metrics --include-archived --start-date "2024-01-01" --end-date "2024-12-31"

Note: Including archived tickets may significantly increase the number of results and processing time, as archived tickets can accumulate over long periods.

Cache Behavior: Requests with and without archived tickets are cached separately, so you can switch between modes without cache conflicts.

Smart Caching

The script includes intelligent caching to avoid unnecessary API calls and improve performance:

How It Works

• Automatic Caching: API responses are cached in tmp/.linear_cache directory
• Cache Key: Based on search criteria (team, dates, etc.)
• Cache Expiry: Cached data expires at the start of the next day
• Cache Hit: Shows "✅ Using cached data" when cache is used
• Cache Miss: Shows "🔄 Cache miss or expired" when fetching fresh data

Usage Examples

# First run - fetches from API and caches the response
./bin/kanban_metrics --start-date "2025-01-01"

# Second run - uses cached data (much faster!)
./bin/kanban_metrics --start-date "2025-01-01"
# ✅ Using cached data (5015 issues)

# Force fresh data (bypass cache)
./bin/kanban_metrics --start-date "2025-01-01" --no-cache

# Different search criteria = different cache
./bin/kanban_metrics --start-date "2025-02-01"  # New API call

Cache Debugging

# See cache operations in detail
DEBUG=1 ./bin/kanban_metrics
📄 Fetching page 1...
🔍 GraphQL Query: issues(first: 250)
📄 Fetching page 2...

📈 Timeseries Analysis

The script now includes powerful timeseries analysis capabilities to track status changes over time:

Usage Examples

# Include timeseries analysis in the report
./bin/kanban_metrics --timeseries

# View detailed timeline for a specific issue
./bin/kanban_metrics --timeline "ISSUE-123"

# Export timeseries data as JSON
./bin/kanban_metrics --timeseries --format json

# Export timeseries data as CSV
./bin/kanban_metrics --timeseries --format csv

Timeseries Features

1. Status Transitions: Most common state changes across all tickets
2. Average Time in Status: How long tickets typically spend in each status
3. Daily Activity: Recent status change activity by date
4. Individual Timelines: Complete history for specific tickets

Sample Output

The timeseries analysis provides:

• Status Flow: created → In Progress (47 times), To test → Done (38 times)
• Time Analysis: In Review: 5.65 days average, Todo: 1.54 days average
• Activity Tracking: Daily breakdown of all status changes
• Individual History: Complete timeline for any ticket: 2025-06-19 15:08 | Backlog → In Progress

This helps identify:

• 🔍 Bottlenecks: Statuses where work gets stuck longest
• 📊 Flow Patterns: Most common paths through your workflow
• ⚡ Process Issues: Unusual transitions or delays
• 📈 Trend Analysis: How activity changes over time

Export Features with Individual Ticket Details

The --ticket-details flag enables detailed export of individual ticket data in all output formats (table, JSON, CSV).

Output Format Examples

Table Format (--format table --ticket-details):

🎫 INDIVIDUAL TICKET DETAILS
+----------+---------------------------+------+----------+----------+
| ID       | Title                     | State| Created  | Completed|
+----------+---------------------------+------+----------+----------+
| PROJ-123 | User authentication       | Done | 2024-06-01| 2024-06-08|
| PROJ-124 | Login bug fix             | Done | 2024-06-02| 2024-06-07|
+----------+---------------------------+------+----------+----------+

JSON Format (--format json --ticket-details):

{
  "overall_metrics": { ... },
  "team_metrics": { ... },
  "individual_tickets": [
    {
      "identifier": "PROJ-123", 
      "title": "User authentication",
      "state": { "name": "Done" },
      "calculated_metrics": {
        "cycle_time_days": 6.25,
        "lead_time_days": 7.29
      }
    }
  ]
}

CSV Format (--format csv --ticket-details):

ID,Identifier,Title,State,Team,Assignee,Priority,Cycle Time (days),Lead Time (days)
abc123,PROJ-123,User authentication,Done,Backend Team,John Doe,1,6.25,7.29
def456,PROJ-124,Login bug fix,Done,Frontend Team,Jane Smith,0,1.1,1.9

Key Features

Individual ticket details include:

• All Linear ticket fields (ID, identifier, title, state, team, assignee, priority, estimate)
• Timestamps (created, updated, started, completed, archived)
• Calculated cycle time (started → completed)
• Calculated lead time (created → completed)
• Proper handling of incomplete tickets (empty time fields for in-progress/backlog items)

Note: Individual tickets are only included when using the --ticket-details flag. Without this flag, output contains only aggregated metrics.

Perfect for:

• 📊 Data analysis in Excel, Google Sheets, or BI tools
• 📈 Trend analysis across individual tickets over time
• 🔍 Outlier detection for tickets with unusual cycle/lead times
• 📋 Detailed reporting with ticket-level granularity

Development

Testing & Quality Assurance

This project maintains high code quality with comprehensive testing and automated checks:

• Comprehensive RSpec test suite with high code coverage (minimum 85% overall, 65% per file)
• Zero RuboCop offenses (style and quality checks)
• Brakeman security analysis (no vulnerabilities found)

# Run tests
bundle exec rspec

# Run tests with coverage
COVERAGE=true bundle exec rspec

# Run code style checks
bundle exec rubocop

# Run security analysis
bundle exec brakeman --force

# Run all checks locally (like CI)
./bin/ci

# Run the main kanban metrics tool
./bin/kanban_metrics

Continuous Integration & Pull Request Analysis

The project includes comprehensive CI/CD with both CircleCI and GitHub Actions:

GitHub Actions (Immediate PR Feedback)

• 🔍 Inline code review with RuboCop violations in PR comments
• ⚡ Fast feedback (< 2 minutes) on pull requests
• 🎯 Targeted testing for changed files only
• 💬 Automated summaries for security and quality issues
• 📊 Coverage impact analysis

CircleCI (Comprehensive Pipeline)

• Automated testing on every commit
• Code coverage reporting with detailed HTML reports
• Security scanning with Brakeman (multiple formats)
• Code quality checks with RuboCop
• Nightly comprehensive audits

See the GitHub Actions workflows for detailed CI/CD configuration.

Contributing

1. Fork the repository
2. Create a feature branch
3. Run tests locally: ./bin/ci-local
4. Commit your changes
5. Push and create a pull request

All pull requests must pass the CI pipeline before merging.