Docs
Integrations
Linear Integration

Linear Integration

Connect your Linear workspace to AgenticAnts to route compliance notifications and map agents to Linear teams.

Linear is a modern project management tool for software teams. The AgenticAnts integration lets you map agents to Linear teams and automatically create issues when compliance violations are detected.

What You Can Do

  • Map agents to Linear teams — route each agent's notifications to the correct Linear team
  • Send compliance notifications — create Linear issues from unapproved model violations in the Risk tab
  • Multi-channel notify — select Linear alongside Slack and Jira in a single notification dialog
  • Agent visibility — see the linked Linear team badge on agent detail panels in the Command Center

Getting Started

Step 1: Generate a Linear API Key

  1. Go to Linear Settings > Security (opens in a new tab)
  2. Under Personal API keys, click Create key
  3. Give it a label (e.g., "AgenticAnts Integration")
  4. Copy the key immediately — it starts with lin_api_
⚠️

Select "All teams" scope when creating the key so AgenticAnts can access both public and private teams.

Step 2: Connect Linear in AgenticAnts

  1. Navigate to Project Settings > Integrations > Linear
  2. Click Connect Linear
  3. Paste your API key (lin_api_...) in the dialog
  4. Click Connect

Once connected, you'll see a green Connected indicator with your workspace name.

Step 3: Map Agents to Linear Teams

After connecting, you can map your AI agents to specific Linear teams:

  1. On the same Linear integration page, scroll to Agent Team Mappings
  2. Select an agent from your project
  3. Choose the Linear team that should receive issues for that agent
  4. Save the mapping

This ensures compliance notifications for that agent are routed to the correct Linear team.

Step 4: Send Notifications from Risk Tab

When unapproved models are detected for an agent:

  1. Open the agent in the Agent Command Center
  2. Go to the Risk tab
  3. In the Unapproved Models section, click the Linear icon next to "View Traces"
  4. A notification dialog opens with Linear pre-selected — you can also select Slack and Jira
  5. Click Send Notification to create a Linear issue with the violation details

Security

  • Encrypted storage — API keys are encrypted at rest using AES encryption before being stored
  • Per-project isolation — each project has its own Linear integration; credentials are never shared
  • Access control — only users with automations:CUD permission can connect/disconnect the integration
  • Read-only access — users with automations:read can view integration status and issue details
  • No key exposure — API keys are never returned to the frontend after initial connection

Troubleshooting

Connection failed — "Invalid API key"
  1. Verify your API key starts with lin_api_
  2. Make sure the key hasn't been revoked in Linear settings
  3. Check that the key has "All teams" scope
  4. Try generating a new key
No teams showing after connection
  1. Click Refresh Status on the connection card
  2. Verify your API key has access to teams (not just personal scope)
  3. If the error persists, disconnect and reconnect with a new key — the original key may have been revoked
Issue status not updating

Status refreshes from Linear on each page view. If the status seems stale:

  1. Refresh the page to trigger a sync
  2. Check that the Linear integration is still connected (API key not revoked)
  3. Newly created issues (less than 10 seconds old) skip the refresh to avoid race conditions
"Insufficient permissions" error

You need the AI Steward or Owner role to manage integrations. Contact your project administrator to get the automations:CUD permission.

Next Steps

JIRA IntegrationSlack IntegrationCrewAI Integration
Slack IntegrationOverview