Linear

Integrate Aiqaramba with Linear to sync issues as user journeys and post test run results back as comments. See the CI/CD integration guide for the full setup walkthrough.

Setup

Go to Integrations and click Connect Linear. You will be redirected to Linear to authorize the application. After approving, your Linear organization name will appear on the integration card and the sync form will be available.

Syncing Issues as Journeys

Label issues in Linear (e.g. qa-ready) and use the sync endpoint to import them as test journeys. Each synced issue creates a journey with:

  • Name — issue title, prefixed by importance tier
  • Prompt template — issue description converted into agent-executable steps
  • Importance — mapped from Linear priority (P1=critical, P2=high, P3=medium, P4=low)
  • External ref — linear:<issue_id> used for bidirectional linking

Re-syncing updates existing journeys rather than creating duplicates.

Example

curl -X POST \ -H "Authorization: Bearer $AIQARAMBA_API_KEY" \ -H "Content-Type: application/json" \ -d '{"project_id": "your-project-id", "team_id": "TEAM-abc123", "label_name": "qa-ready", "default_entry_url": "https://app.example.com"}' \ https://app.aiqaramba.com/api/v1/linear/sync

Automatic Sync via Webhooks

After saving a sync configuration on the Integrations page, new or updated issues in Linear automatically trigger a background sync. To enable this, create a webhook in Linear (Settings → API → Webhooks):

  • URL — https://your-domain.com/webhooks/linear
  • Resource types — Issues
  • Copy the signing secret and set it as LINEAR_WEBHOOK_SECRET in your environment

Synced journeys appear on the Journeys page (filter by Source: Linear) and on the project Health Board.

Result Feedback

When an agent runs a journey that was synced from Linear, the result is posted back to the linked Linear issue as a comment. This includes the pass/fail status, duration, and a link to the agent detail page.

Full Integration Guide

See the CI/CD Integration guide for a step-by-step walkthrough connecting Linear, GitHub, and your deploy pipeline into one automated loop.

GET /api/v1/linear/teams

List Linear teams

Returns teams in the connected Linear workspace. Use team IDs when triggering a sync.

Status Codes

CodeDescription
200OK
400Linear not configured
401Unauthorized

Response Body

[
  {
    "id": "team-abc123",
    "name": "Engineering",
    "key": "ENG"
  }
]
GET /api/v1/linear/teams
cURL 
Response 
POST /api/v1/linear/sync 
Sync Linear issues as user journeys
Imports issues from a Linear team that have the specified label into Aiqaramba as test journeys. Issues are matched by external reference (linear:<issue_id>) so re-syncing updates existing journeys rather than creating duplicates. Issue title becomes the journey name (prefixed by importance tier), and the description is converted into an agent-executable prompt template.
Parameters
ParameterTypeInRequiredDescription
 
project_iduuidbodyYesAiqaramba project to create journeys in 
team_idstringbodyYesLinear team ID (from /api/v1/linear/teams) 
label_namestringbodyYesOnly sync issues with this label 
default_entry_urlstringbodyNoDefault starting URL for created journeys (used when not specified in the issue) 
Status Codes
CodeDescription
 
200Sync completed
400Validation error
401Unauthorized
Response Body
{
  "created": 3,
  "updated": 1,
  "skipped": 2
}
POST /api/v1/linear/sync
 
 
 
 
 
cURL 
Response 
POST /webhooks/linear 
Linear webhook endpoint
Receives webhook events from Linear. When an issue is created or updated, checks for saved sync configurations matching the issue's team and enqueues a background sync job. Signature verification uses the LINEAR_WEBHOOK_SECRET environment variable (HMAC-SHA256, sent in the Linear-Signature header). Returns 200 for all valid payloads. Only Issue events with action create or update trigger syncs.
Status Codes
CodeDescription
 
200Webhook received
401Invalid signature
POST /webhooks/linear
 
cURL 
Response