Linear

Some issues detected by Monte Carlo take time to fix, or require work from engineers who plan their work in Linear. The Linear integration lets you create Linear tickets directly from Monte Carlo and keep their status in sync.

This integration allows:

• Users in Monte Carlo to click a button to create a Linear ticket from a recommended action on an agent health issue (the Reinforcement loop view in AI Observability).
• Status updates from those Linear tickets to be synced back to Monte Carlo, so you can see the latest ticket state without leaving the app.

Note: one Linear integration can be configured per Monte Carlo account.

Integration setup

A user with permission to edit integrations (e.g. an Account Owner) must go to Settings > Integrations. Click Add, search for Linear, and complete the form.

Input:

• Integration name: this gives a superficial name to the integration within Settings, e.g. "Linear"
• Linear API token: a personal API key created in Linear. In Linear, go to Settings > Security & access > Personal API keys to create one. See Linear's API docs for details.

When creating the API key in Linear, only the minimum permissions are needed. Under Permissions, choose Only select permissions... and enable:

• Read
• Create issues
• Create comments

Write and Admin are not required. Under Team access, you can grant all teams or restrict the key to select teams — Monte Carlo will only be able to create tickets in teams the key can access.

The Linear API token inherits the permissions of the user who created it, so Monte Carlo will only be able to see teams and create tickets where that user has access.

Click Save. Monte Carlo validates the token against Linear, and the form stays open so you can finish two optional steps:

• Default Linear team: once the token is saved, a team picker is populated from your Linear workspace. New Linear tickets use this team unless a team is selected at creation time.
• Sync Linear ticket status to Monte Carlo: see below.

Syncing status from Linear tickets back to Monte Carlo

Syncing the status of Linear tickets back to Monte Carlo is optional and requires registering a webhook in Linear. Because Linear only issues the webhook signing secret after the webhook is created on their side, setup happens in two steps:

1. In the integration form, toggle Sync Linear ticket status to Monte Carlo to on and click Save. Monte Carlo generates a webhook URL for the integration and displays it in the form.
2. In Linear, go to Settings > API > Webhooks and create a webhook:
   • URL: paste the webhook URL from Monte Carlo.
   • Signing secret: the create-webhook form displays a signing secret — copy it before creating the webhook.
   • Data change events: select Issues.
   • Team selection: choose the teams whose issues should sync. Note: this cannot be modified after the webhook is created.
3. Back in Monte Carlo, paste the signing secret into the Webhook secret field and click Save again.

Once the secret is saved, status sync is enabled. Monte Carlo validates the signature of every incoming webhook against the stored secret, and updates the linked ticket's status whenever the issue's workflow state changes in Linear. A status update in Monte Carlo does not have any impact on the status of a Linear ticket.

To rotate the webhook secret later, edit the integration and enter the new secret in the Webhook secret field.

Creating a Linear ticket from Monte Carlo

After the integration is set up, users can create Linear tickets from recommended actions on agent health issues in the Reinforcement loop view:

• Open an agent in AI Observability and go to the Reinforcement loop tab, then open an issue.
• Each recommended action offers an Add Linear ticket button. Clicking it creates a ticket with the title and description pre-populated from the issue, including its context and evidence.
• Once created, the ticket identifier is shown on the issue with a 1-click link to open it in Linear, along with its latest synced status.

One Linear ticket is created per issue — if a ticket already exists for the issue, the existing ticket is shown instead of creating a duplicate.

If the integration has not been configured yet, users with permission to edit integrations will see a Connect button that opens the integration form directly from the issue page.

Permissions

• Connecting or editing the integration requires permission to edit integrations in Settings (e.g. an Account Owner).
• Creating a Linear ticket requires edit access to alerts on the relevant asset — domain-restricted editors can only create tickets for assets in their domains.