> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ravenna.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Ticket replication

> Sync tickets bidirectionally between Ravenna and Linear with automatic updates to comments, status, priority, and details across both tools.

Ticket replication keeps Ravenna tickets and Linear issues synchronized with bidirectional updates. When you enable replication for a channel, tickets and their updates automatically sync between platforms.

## How ticket replication works

Ticket replication synchronizes:

* **Ticket creation** - New tickets in either system create linked issues in the other
* **Comments** - Comments sync bidirectionally between platforms
* **Status changes** - Status updates in one system reflect in the other based on your mappings
* **Ticket details** - Descriptions, priorities, and other fields sync automatically

<Info>
  Ticket replication is configured per channel, allowing different sync behaviors for different teams or workflows.
</Info>

## Setup

<Steps>
  <Step title="Connect Linear integration">
    Install and configure the Linear integration in **Settings** > **Integrations**.

    <Callout icon="link" color="#6B7280">
      Follow the [Linear setup guide](/integrations/linear/setup) to connect your Linear workspace
    </Callout>
  </Step>

  <Step title="Enable replication for channel">
    Navigate to the channel where you want to enable replication:

    1. Open **Channel Settings**
    2. Go to **Ticket Replication**
    3. Enable replication for Linear
    4. Click **Configure** to set channel-specific preferences
  </Step>

  <Step title="Configure channel preferences">
    Set channel-specific replication preferences:

    * **Linear team** - Select which Linear team to sync with
    * **Project** (optional) - Choose a specific project within the team
    * **Status mapping** - Map Ravenna statuses to Linear states
    * **Replication direction** - Choose bidirectional or one-way sync
  </Step>

  <Step title="Test replication">
    Create a test ticket in the channel to verify replication works correctly.
  </Step>
</Steps>

## Replication directions

Configure how tickets sync between systems:

**Ravenna → Linear**

* Tickets created in Ravenna automatically create Linear issues
* Updates in Ravenna push to Linear
* Useful for support teams creating issues for product/engineering teams

**Linear → Ravenna**

* Issues created in Linear automatically create Ravenna tickets
* Updates in Linear push to Ravenna
* Useful for tracking product work in your support system

**Bidirectional**

* Changes in either system sync to the other
* Full two-way synchronization
* Best for teams collaborating across both platforms

## Status mapping

Status mapping ensures ticket states sync correctly between Ravenna and Linear. Mappings apply to both **initial ticket creation** and **ongoing status updates**, so a replicated ticket starts in the correct Linear state.

1. Configure mappings when setting up channel replication
2. Map each Ravenna status to a corresponding Linear state
3. Mappings are per-channel, allowing different configurations
4. When a ticket is created or a status changes in one system, the mapped status is applied in the other

If no status mapping is configured, the integration defaults to the first available backlog or unstarted state in the Linear team.

<Info>
  Linear states are team-specific. Ensure your mapped states exist in your Linear team's workflow.
</Info>

## Per-channel configuration

Each channel can have different replication settings:

**Product channel example:**

* Replicates to Linear team "Product"
* Syncs to "Roadmap" project
* Bidirectional sync enabled

**Engineering channel example:**

* Replicates to Linear team "Engineering"
* No specific project (uses team default)
* One-way sync (Ravenna → Linear only)

This flexibility allows different teams to use replication in ways that match their workflow.

## What syncs

**Automatically synced:**

* Ticket/issue creation
* Comments and replies
* Status changes (based on your mappings)
* Ticket descriptions and titles
* Priority (when mapped)
* Assignee (when users exist in both systems)

**Not synced:**

* Custom fields
* Attachments
* Ticket history and audit logs
* Internal notes in Ravenna
* Linear-specific fields (estimates, cycles)

## User mapping

Linear replication automatically maps users between systems:

* When a ticket is assigned in Ravenna, the integration looks for a Linear user with the same email
* If found, the Linear issue is assigned to that user
* If not found, the issue remains unassigned in Linear

The same logic applies when issues are assigned in Linear.

## Empty title and description fallbacks

If a Ravenna ticket is replicated to Linear without a title or description, the integration substitutes placeholder values so the Linear issue is always created successfully:

* Missing title → `Empty title`
* Missing description → `Empty description`

Update the ticket in Ravenna to push the real values to the linked Linear issue.

## Troubleshooting

**Tickets not syncing:**

* Verify the integration is connected in Settings > Integrations
* Check that replication is enabled for the channel
* Confirm the Linear team and project are correctly configured
* Ensure status mappings are set up

**Status changes not syncing:**

* Verify status mappings exist for both directions
* Check that the mapped status exists in your Linear team's workflow
* Confirm the Linear team supports the status transition

**Comments not appearing:**

* Comments sync with a short delay (typically a few seconds)
* Check that the Linear issue is linked to the Ravenna ticket
* Verify webhook configuration in integration settings

**User assignments not syncing:**

* Ensure users have accounts in both systems with matching email addresses
* Check that the Linear user is a member of the target team
* Verify the Ravenna user has access to the workspace

<Callout icon="link" color="#6B7280">
  Need help? Contact support or visit the [Linear setup guide](/integrations/linear/setup) for integration configuration
</Callout>

## Best practices

* **Map statuses before enabling replication** - Set up status mappings first to avoid sync issues
* **Test with one channel** - Enable replication for a single channel first to verify configuration
* **Document your mappings** - Keep track of which channels sync to which Linear teams
* **Use team-specific channels** - Create separate channels for different Linear teams
* **Monitor initial sync** - Watch the first few tickets to ensure replication works as expected
* **Match user emails** - Ensure team members have matching email addresses in both systems