Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/jonwiggins/optio/llms.txt

Use this file to discover all available pages before exploring further.

Optio’s Linear integration periodically fetches issues from your Linear workspace and creates tasks from them. When the agent finishes and the PR merges, Optio can mark the original Linear issue as done.
GitHub Issues and Linear can both be active simultaneously. Optio runs a separate sync worker for each enabled ticket provider and deduplicates issues so the same work item is never created twice.

​
How ticket sync works

The ticket sync worker runs on a regular schedule. On each cycle it:
  1. Fetches Linear issues that have the configured label (default: optio) and are not in a completed or canceled state.
  2. For each issue not yet tracked by Optio, creates a task using the issue title as the task title and the issue description as the prompt.
  3. Queues each new task for the agent.
When a task’s PR is merged, Optio calls back to Linear and moves the original issue to the Done workflow state for its team.

​
Setup

1

Create a Linear API key

In Linear, go to Settings → API → Personal API keys and create a new key. Copy the key — you will not be able to see it again.
2

Find your team ID (optional)

If you want to scope the sync to a specific team, find the team ID in Linear under Settings → [Team] → General. The team ID is the UUID shown in the URL or settings page. You can skip this step to sync issues from all teams.
3

Configure the ticket provider in Optio

Go to Settings → Integrations → Ticket providers and click Add provider. Select Linear and fill in:
FieldDescription
API keyThe Personal API key you created in step 1
Team ID(Optional) Restrict sync to a specific Linear team
LabelThe issue label that marks an issue as ready for Optio (default: optio)
Click Save. Optio will run the first sync immediately.
4

Label issues in Linear

Add the optio label (or whichever label you configured) to any Linear issue you want the agent to work on. The next sync cycle will pick it up.

​
Fields synced from Linear

Linear fieldOptio task field
Issue titleTask title
Issue description (Markdown)Task prompt
Issue identifier (e.g. ENG-42)ticketExternalId
Issue URLStored in task metadata
The issue’s priority, team, and project are stored in task metadata and available for reference but are not used to set task priority automatically.

​
Bidirectional updates

When Optio completes a task that originated from a Linear issue:
  • Optio searches for the Linear issue by its identifier.
  • It sets the issue’s state to the first completed-type workflow state it finds for the team (typically “Done”).
Optio matches the Linear issue using the identifier stored at sync time. If the issue is moved to a different team in Linear between sync and completion, Optio may not be able to update it. This is uncommon in practice.

​
Triggering a manual sync

You can trigger a sync at any time from the UI under Settings → Integrations → Ticket providers by clicking Sync now, or via the API: 
POST /api/tickets/sync
This runs the full sync for all enabled ticket providers.

​
Disabling or removing the integration

To pause syncing without losing the configuration, go to Settings → Integrations → Ticket providers, find the Linear entry, and toggle it off. To remove it entirely, click Delete.

Build docs developers (and LLMs) love

Get started for freeTalk to us