Linear - Setup Guide

Linear project management and issue tracking integration for Axellero.

Step 1: Create Credential

Getting Your API Key

1. Log in to your Linear workspace
2. Click on your profile avatar in the top-left corner
3. Navigate to Settings > Security & access > API keys
4. Click Create new API key
5. Enter a descriptive name (e.g., "Axellero Integration")
6. Copy the generated API key immediately (it won't be shown again)

Adding Credential to Axellero

1. Navigate to Application > Integrations > Credentials
2. Click "Add Credential"
3. Select Bearer
4. Enter:
   • Name: "Linear Production"
   • Access Token: Your Linear API key
5. Click Save

Axellero securely encrypts credentials and handles authentication automatically.

Step 2: Create Connector

1. Navigate to Application > Integrations > Connectors
2. Click "Add Connector"
3. Select Linear from the list
4. Configure:
   • Name: "Linear - Production"
   • Credential: Select the Bearer credential you created
5. Click Save
6. Test the connection using the "Test" button

The connector is now available in any workflow or agentflow.

Step 3: Create Trigger

For supported events and payload examples, see main documentation.

3.1 Create Webhook in Linear

Linear requires manual webhook registration:

1. Go to Linear Settings > API > Webhooks
2. Click New Webhook
3. Enter the webhook URL (you'll get this from Axellero in Step 3.2)
4. Copy the Signing secret (you'll need this for Axellero)
5. Select the events you want to receive:
   • Issue events (create, update, remove)
   • Comment events (create, update, remove)
   • Project events (create, update, remove)
   • Cycle events (create, update, remove)
   • Label events (create, update, remove)
6. Click Create webhook

3.2 Create Trigger in Axellero

1. Navigate to Integrations > Triggers
2. Click "Add Trigger" (+) button
3. Select your Linear connector
4. Configure trigger options (see table below)
5. Click Save
6. Copy the generated Webhook URL
7. Go back to Linear and update your webhook with this URL

Trigger Configuration Options

Available Event Types:

Manual webhook registration required: Linear webhooks must be configured in the Linear dashboard. Copy the Axellero webhook URL and register it in Linear Settings > API > Webhooks.

3.3 Add Trigger to Workflow

1. Open Workflow Builder
2. Find your Linear trigger in the Triggers section
3. Drag to canvas as starting node
4. Build workflow logic after the trigger

3.4 Test the Trigger

1. Create or update an issue in Linear
2. Check workflow execution logs in Axellero
3. Verify trigger data via {{ctx.nodes.linear_trigger.outputs.data}}

Workflow Examples

Example 1: Issue Notification to Telegram

Send Telegram notifications when new issues are created.

Workflow Steps:

1. Linear Trigger: Events = Issue:create
2. Telegram - sendMessage: Send notification

Configuration:

{
  "chatId": "{{ctx.vars.teamChatId}}",
  "text": "New issue: {{ctx.nodes.linear_trigger.outputs.data.data.identifier}} - {{ctx.nodes.linear_trigger.outputs.data.data.title}}"
}

Example 2: Auto-Label High Priority Issues

Automatically add labels to urgent issues.

Workflow Steps:

1. Linear Trigger: Events = Issue:create
2. Condition: Check if priority is Urgent (1)
3. Linear - updateIssue: Add "Urgent" label

Configuration:

{
  "id": "{{ctx.nodes.linear_trigger.outputs.data.data.id}}",
  "labelIds": "urgent-label-id"
}

Example 3: Daily Sprint Summary via Gmail

Send daily sprint progress via email.

Workflow Steps:

1. Schedule Trigger: Daily at 9:00 AM
2. Linear - listCycles: Get current cycle
3. Linear - listIssues: Filter by cycle
4. Gmail - sendMessage: Send summary email

Configuration for listCycles:

{
  "teamId": "{{ctx.vars.teamId}}",
  "filter": "current"
}

Example 4: Sync Issues to GitLab

Create GitLab issues when Linear issues are created.

Workflow Steps:

1. Linear Trigger: Events = Issue:create
2. GitLab - createIssue: Create corresponding issue

Configuration:

{
  "projectId": "{{ctx.vars.gitlabProjectId}}",
  "title": "[Linear] {{ctx.nodes.linear_trigger.outputs.data.data.title}}",
  "description": "{{ctx.nodes.linear_trigger.outputs.data.data.description}}\n\nLinear: {{ctx.nodes.linear_trigger.outputs.data.url}}"
}

Troubleshooting

Common Issues

Webhook not receiving events

• Verify webhook URL is correctly registered in Linear
• Check webhook is enabled in Linear settings
• Ensure signing secret matches between Linear and Axellero

API key not working

• API keys may be revoked if account permissions change
• Generate a new API key if the current one doesn't work
• Ensure you copied the full key without extra spaces

Connection test fails

• Verify credential is correctly configured as Bearer type
• Check network/firewall rules allow connections to api.linear.app
• Ensure API key has not been deleted in Linear

Security Best Practices

• Store credentials in Axellero Credential Manager (encrypted)
• Use webhook signature verification (always configure the secret)
• Use API keys with minimum required permissions
• Rotate API keys periodically
• Never share API keys in code or logs

Resources

• Linear API Documentation
• Linear GraphQL API Reference
• Linear Webhooks Documentation
• Back to Main Documentation