Insync - Linear to Jira Sync Service

A service that synchronizes tickets between Linear and Jira to ensure consistent workflow across both platforms.

Overview

The Insync service provides bidirectional synchronization between Linear and Jira platforms, ensuring that:

• When an issue is created in Linear, it is also created in Jira
• Status updates are synchronized between both platforms (Todo → To Do, In Progress → In Progress, etc.)
• Changes to issue details are reflected in both systems

The service uses webhooks from both platforms to detect changes and APIs to make corresponding updates.

Architecture

The service follows a webhook-driven architecture:

┌─────────────────┐            ┌──────────────────┐            ┌─────────────────┐
│                 │            │                  │            │                 │
│   Linear        │ ◄─────┐    │  Insync Service  │    ┌─────► │   Jira          │
│                 │       │    │                  │    │       │                 │
│  Issues API     │ ◄─────┼────┤  Webhook         ├───►│──────►│  Issues API     │
│  Webhooks       │       │    │  Processing      │    │       │  Webhooks       │
│                 │ ◄─────┘    │                  │◄───┘       │                 │
└─────────────────┘            └──────────────────┘            └─────────────────┘

API Documentation

For detailed information about the APIs and webhooks used by both platforms, see docs/api.md

Workflow Diagrams

For detailed workflow diagrams showing how the sync process works, see docs/workflow-diagrams.md

Features

• Bidirectional Sync: Changes in either system are reflected in the other
• Status Mapping: Automatic mapping between Linear and Jira status systems
• Real-time Updates: Uses webhooks for immediate synchronization
• Conflict Resolution: Handles potential sync conflicts gracefully
• Error Handling: Robust error handling and retry mechanisms
• Field Mapping: Maps common fields between the two systems

Status Mapping

Linear Status	Jira Status
Todo	To Do
In Progress	In Progress
In Review	In Review / Code Review
Done	Done

Implementation Plan

The service will be implemented in phases:

Phase 1: Basic Sync

• Create issues in Jira when they're created in Linear
• Sync status changes between platforms
• Handle basic field mapping

Phase 2: Enhanced Sync

• Enable updates to issue details (description, assignee, etc.)
• Handle comment synchronization
• Add more comprehensive field mapping

Phase 3: Advanced Features

• Support for attachments
• Custom field mapping
• Enhanced error handling and reporting

Getting Started

To set up the service locally:

1. Clone the repository
2. Install dependencies
3. Configure API keys for both Linear and Jira
4. Set up webhook endpoints
5. Run the service

Configuration

The service requires the following configuration:

• Linear API key
• Jira API key
• Jira site URL
• Webhook endpoint URLs
• Field mapping configuration

Security

• All webhook endpoints use HTTPS
• HMAC signature verification for webhook authenticity
• API keys stored securely
• Rate limiting to prevent abuse

Monitoring and Logging

The service includes:

• Comprehensive logging for sync operations
• Error tracking and alerting
• Performance metrics
• Sync status reporting

Development

Prerequisites

• Go 1.19+
• Access to Linear workspace
• Access to Jira instance

Running Locally

go mod tidy
go run main.go

Contributing

We welcome contributions to improve the sync service. Please see our contributing guidelines for more information.

License

This project is licensed under the MIT License.