Linear Integration

The Linear integration allows you to automatically create issues in Linear from Tape workflow errors and notifications. This is especially useful for development teams that use Linear for issue tracking and workflow management.

What Can You Do with the Linear Integration?

  • Automatically create Linear issues from Tape workflow errors
  • Set issue priorities based on notification importance
  • Assign issues to specific Linear teams
  • Include detailed error information and links back to Tape
  • Link workflow failures directly to your development workflow

Setting Up Linear Integration

Step 1: Get Your Linear API Key

First, you need to generate an API key in Linear:

  1. Log in to your Linear account
  2. Go to Settings (the gear icon in the lower-left)
  3. Select API from the left sidebar
  4. Under “Personal API Keys”, click Create Key
  5. Give your API key a name (e.g., “TapeAlert”)
  6. Copy the generated API key - you’ll need this in the next step

Step 2: Find Your Linear Team ID

You’ll also need to identify which Linear team should receive the issues:

  1. In Linear, the teams you have access to are listed in the left hand menue
Your Linear Teams
Your Linear Teams List

Step 3: Add Linear as a Destination

Next, configure Linear as a notification destination:

  1. Navigate to your webhook in TapeAlert
  2. Click Add Destination
  3. Select Linear as the destination type
  4. Enter your Linear API key
  5. A dropdown will be populated with the teams - Select the one you want
  6. Select a default priority for created issues (1-4)
  7. Click Save

Issue Priority Settings

Linear uses a 1-4 priority scale, which you can configure when setting up the destination:

  • Priority 1: Urgent - Requires immediate attention
  • Priority 2: High - Should be addressed soon
  • Priority 3: Medium - Address in normal course of work
  • Priority 4: Low - Address when time permits

Select the appropriate default priority for issues created by this destination. For critical workflows, you might choose a higher priority.

Testing Your Linear Integration

After setting up the Linear destination, you should test it:

  1. From your destination settings, click the Test button
  2. A test issue will be created in your Linear team
  3. Verify that the issue appears correctly in Linear
  4. Check that the issue details and formatting are as expected

Issue Content Format

Issues created in Linear include:

  • Title: The notification type and workflow name
  • Description: Detailed error information formatted in markdown
  • Priority: The priority level you configured
  • Links: Direct links back to the Tape workflow and record (when available)
  • Metadata: Creation timestamp and a note about the source

Troubleshooting

If you’re having issues with your Linear integration:

Issues Not Being Created

  • Verify that your API key is correct and has not expired
  • Ensure your API key has permission to create issues
  • Check that the team ID is correct
  • Review notification logs for any error messages

Content Issues

  • Make sure the Linear issue descriptions aren’t exceeding maximum length
  • Check if there are any special characters causing formatting problems

Best Practices

  • Team Selection: Create separate destinations for different Linear teams
  • Priority Management: Use appropriate priority levels based on notification importance
  • Issue Templates: Consider creating Linear issue templates that align with notifications
  • Automation Rules: Set up Linear automation rules to route issues based on labels or content
  • Regular Review: Periodically check that automated issues are being handled properly

Limitations

  • Issues are created as standalone items and not linked to specific workflows in Linear
  • The integration cannot update existing issues, only create new ones
  • Custom fields in Linear are not supported

Next Steps