> ## 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.

# Setup

> Connect Linear to Ravenna using OAuth from your Linear workspace settings to enable bidirectional issue and ticket synchronization across teams.

<Info>Connect to Linear using OAuth authentication</Info>

This guide walks you through connecting to your Linear workspace to enable bidirectional issue synchronization.

## Prerequisites

Before you begin, ensure you have:

* Admin access to your Linear workspace
* Linear workspace with active projects and teams

## Setup guide

<Steps>
  <Step title="Navigate to integrations">
    1. Go to **Settings > Integrations**
    2. Find **Linear** in the Ticketing section
  </Step>

  <Step title="Select Linear integration">
    Click **Connect** on the Linear integration card
  </Step>

  <Step title="Authorize with Linear">
    1. You'll be redirected to Linear's authorization page
    2. Review the requested permissions:
       * Read and write issues
       * Read projects and teams
       * Read and write comments
    3. Click **Authorize** to grant access
  </Step>

  <Step title="Complete setup">
    After authorization, you'll be redirected back with the integration connected
  </Step>

  <Step title="Link tickets to issues">
    1. Go to a ticket you want to sync
    2. Click the **Link** button or integration menu
    3. Connect it to an existing Linear issue
    4. Updates will now sync bidirectionally
  </Step>
</Steps>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Authorization fails">
    **Cause**: Insufficient permissions or expired session

    **Solution**:

    * Ensure you have admin permissions in Linear
    * Try disconnecting and reconnecting the integration
    * Clear browser cache and retry authorization
    * Verify your Linear workspace is accessible
  </Accordion>

  <Accordion title="Issues not syncing">
    **Cause**: Ticket not properly linked or permission issues

    **Solution**:

    * Verify the ticket is linked to a Linear issue
    * Check that team and project IDs are valid
    * Ensure the authorized user has permission to edit issues
    * Try unlinking and relinking the ticket
  </Accordion>

  <Accordion title="Missing projects or teams">
    **Cause**: Projects not accessible or integration needs refresh

    **Solution**:

    * Refresh the integration by disconnecting and reconnecting
    * Ensure the Linear workspace has active projects
    * Verify the authorized user has access to the teams
    * Check team permissions in Linear
  </Accordion>

  <Accordion title="Permission errors">
    **Cause**: OAuth authorization missing required permissions

    **Solution**:

    * Verify the OAuth authorization granted all required permissions
    * Re-authorize the integration with full permissions
    * Check Linear workspace settings for app restrictions
    * Ensure the user has team admin access
  </Accordion>
</AccordionGroup>

## Sync interval configuration

Control how frequently Ravenna synchronizes data from your Linear workspace. By default, Ravenna syncs every 5 minutes, but you can adjust this based on your organization's needs.

<Steps>
  <Step title="Navigate to integration settings">
    Go to **Settings > Integrations** and click your connected Linear integration.
  </Step>

  <Step title="Configure sync interval">
    In the integration settings, locate the **Sync Interval** field and enter your desired interval in minutes.

    **Recommended intervals:**

    * **5 minutes** (default): Best for active teams needing near-real-time sync
    * **15 minutes**: Good balance for most teams
    * **30-60 minutes**: Suitable for less active projects or to reduce API usage
  </Step>

  <Step title="Save changes">
    Click **Save** to apply the new sync interval.
  </Step>
</Steps>

<Info>
  The sync interval affects how quickly changes in Linear appear in Ravenna and vice versa. Lower intervals provide faster updates but increase API usage.
</Info>