Linear

Linear automations automatically create issues in your Linear workspace when recordings or captures are added to a folder. Convert customer feedback, bug reports, and feature requests into actionable engineering tickets without manual data entry.

---

When to Use Linear Automations

Linear automations are ideal for:

• Bug Report Tracking — Convert customer-reported bugs into engineering tickets with video evidence

• Feature Request Management — Automatically create feature request issues from customer feedback

• Support Escalations — Create high-priority issues when critical problems are reported

• Cross-Team Collaboration — Link customer recordings directly to engineering work

• Audit Trail — Maintain complete record of what customers reported and when

• Triage Workflow — Route issues to specific teams and projects automatically

Linear vs. Email/Webhook

Use Linear when:

• Your engineering team uses Linear for issue tracking

• You want automatic issue creation with full context

• You need to assign issues to projects and team members

• You want bi-directional sync with recordings

Use Email when:

• Recipients don't use Linear

• You just need notifications

• You want simpler setup without OAuth

Use Webhooks when:

• You need integration with a different tool

• You want custom payload formatting

• You're building internal automation

---

Prerequisites

Before setting up Linear automations:

1. Linear Account — With issue creation permissions in your workspace

2. Team Access — Admin or owner role to authorize integrations

3. Screendesk Plan — Pro or Enterprise plan to enable automations

4. Folder — Created in Screendesk to trigger the automation

---

Setup

Connect Linear to Screendesk (First-time only)

Navigate to your integrations:

1. Click your avatar in the top right corner

2. Select Account Settings

3. Go to Integrations & Automations → Integrations

4. Find Linear in the list

5. Click Connect Linear

You'll see a dialog showing the permissions Screendesk requires:

• Create and read issues

• Read teams, projects, and team members

• Read and create labels

• Read workflows and cycles

Click Authorize to proceed.

OAuth State

The authorization window will redirect you back to Screendesk. This happens automatically and is secure. If the window closes without redirecting, click Connect Linear again and accept the authorization.

Review Linear connection status

After authorization completes, you'll return to Account Settings → Integrations.

You should see:

• ✅ Linear Connected with your workspace name

• Team name and member count

• Disconnect button (if you need to remove the integration)

Connection Verified

If you see your team name and members list, Linear is successfully connected. You can now create automations in any folder.

Open folder automations

Create an automation in any folder:

1. Navigate to the folder you want to automate

2. Click Settings (gear icon) in the top right

3. Select the Automations tab

4. Click + Add Automation

5. Select Linear from the integration list

Select target team and project

Configure where issues will be created:

Team (required):

• Select the Linear team where issues will be created

• Only one team per automation (create multiple automations for multiple teams)

Project (optional):

• Choose a specific project to organize issues

• Or leave empty to create issues in the team inbox

• Useful for categorizing bug reports vs. feature requests

Workflow Status (optional):

• Set the initial status for new issues

• Backlog — Default starting point for triage

• Todo — Issues ready for work

• In Progress — For urgent items

• Or any custom status in your Linear workflow

Project Selection

If you don't see expected projects:

1. Ensure they're active in Linear (not canceled)

2. Click Refresh in the Linear integration settings

3. Re-save your automation

Only active projects appear in the dropdown.

Configure issue title

Customize how issue titles appear in Linear:

Default title template:

{{item.title}}

Example outputs:

Checkout page crashes on iOS
User can't reset password
Feature request: Dark mode toggle

Other title examples:

For bug reports:

🐛 {{item.title}}

For feature requests:

💡 Feature: {{item.title}}

Including folder context:

[{{folder.name}}] {{item.title}}

For customer-specific issues:

Customer {{creator.email}}: {{item.title}}

Title Length

Keep titles under 100 characters for clarity. Linear will truncate very long titles in the UI.

View all available template variables →

Configure issue description

Create a rich issue description with recording context:

Default description template:

**Recording from Screendesk**

**Title:** {{item.title}}
**From:** {{creator.name}} ({{creator.email}})
**Folder:** {{folder.name}}

**View recording:** {{item.url}}

---

This issue was automatically created from a recording uploaded to Screendesk.

Example: Detailed bug report description

## Bug Report

A customer submitted a recording that describes the issue below.

**Reported by:** {{creator.email}}
**Folder:** {{folder.name}}

### Description
{{item.title}}

### Watch Recording
[View on Screendesk]({{item.url}})

---

### Recording Details
* **Duration:** {{item.duration}} seconds
* **Browser:** {{item.browser}}
* **OS:** {{item.os}}
* **Screen Resolution:** {{item.resolution}}
* **Recorded:** {{item.created_at}}

### Technical Information

**Console Errors:**

{{item.console_errors}}

**Network Errors:**

{{item.network_errors}}

---

This issue was automatically created from a customer recording on Screendesk.

Example: Feature request description

## Feature Request

A customer requested the following feature.

**Suggested by:** {{creator.email}} ({{creator.name}})

### Feature Description
{{item.title}}

### Customer Recording
[View request on Screendesk]({{item.url}})

**Recording Duration:** {{item.duration}} seconds

---

This feature request was automatically created from a customer recording.

Markdown Support

Linear descriptions support full markdown formatting:

• Bold — **text**

• Italic — *text*

• Code blocks — ```

• Links — [text](url)

• Headers — ## Heading

• Lists — * item

Use markdown to format important information. {% endhint %}

View all available variables → {% endstep %}

{% step %}

Set priority level

Assign automatic priority to new issues:

Priority	Level	Linear Value	Use For
No Priority	—	None	General items, low urgency
Low	P3	3	Minor improvements, nice-to-haves
Medium	P2	2	Standard bugs, regular features
High	P1	1	Important bugs, urgent features
Urgent	P0	0	Critical bugs, blocking issues

Recommendations:

• Bug Reports folder — Set to Medium (P2) or High (P1)

• Feature Requests folder — Set to No Priority (triage later)

• Critical Issues folder — Set to Urgent (P0)

Issues can be re-prioritized in Linear after creation.

{% hint style="info" %} Avoid Over-Prioritization

Set automations to Medium or No Priority by default. Let your team manually adjust based on actual impact and customer tier. {% endhint %} {% endstep %}

{% step %}

Apply labels automatically

Organize issues with labels:

To add labels:

1. Click + Add Label

2. Select from your team's available labels

3. Add multiple labels as needed

Suggested labels:

• from-screendesk — Track all automated issues

• customer-reported — Mark customer submissions

• needs-triage — Flag for manual review

• bug or feature-request — Categorize issue type

• high-priority — For urgent folders

• customer-feedback — Specific to feature requests

Example configurations:

For bug reports folder:

from-screendesk, customer-reported, bug, needs-triage

For feature requests folder:

from-screendesk, feature-request, customer-feedback

For critical issues folder:

from-screendesk, urgent, needs-immediate-attention

{% hint style="warning" %} Label Availability

Only labels that exist in your Linear team appear in the dropdown. If you don't see a label you want:

1. Create it in Linear first

2. Return to Screendesk

3. Click Refresh in the Linear integration settings

4. The new label will appear in the dropdown {% endhint %} {% endstep %}

{% step %}

Assign team members (optional)

Auto-assign issues to team members:

Assignee dropdown:

• Select a specific team member

• Or leave unassigned for manual assignment

• Only active team members appear in the list

Recommended approach:

• Leave unassigned for most automations

• Use assignee for on-call or urgent issues

• Let team leads manually assign based on expertise

Example uses:

• Assign critical bugs to on-call engineer

• Assign feature requests to product manager

• Leave general issues unassigned for triage

{% hint style="info" %} Rotating Assignees

Create multiple automations to rotate assignments:

• Automation 1: Assigns to Engineer A

• Automation 2: Assigns to Engineer B

• Assign recordings to different automations manually {% endhint %} {% endstep %}

{% step %}

Test the automation

Before activating, create a test issue:

1. Click Create Test Issue button

2. Check your Linear workspace for the new issue

3. Verify all fields populated correctly:

   • Title matches template

   • Description includes all variables

   • Team and project are correct

   • Labels are applied

   • Assignee is set (if configured)

   • Priority is correct

   • Recording link works

If something looks wrong:

1. Click Back

2. Update the settings

3. Click Create Test Issue again

Delete test issues in Linear: After verifying, you can delete test issues directly in Linear (they won't affect the automation).

{% hint style="success" %} Ready to Activate

Once testing passes, proceed to save. {% endhint %} {% endstep %}

{% step %}

Save and activate

Finalize the automation:

1. Click Save Automation

2. The automation is enabled by default

3. You'll see it listed in the folder's Automations tab

Status indicators:

• ✅ Green toggle — Automation is active

• ⚫ Gray toggle — Automation is disabled

You can disable/enable the automation anytime without deleting it.

From now on, every recording or capture added to this folder will automatically create an issue in Linear.

{% hint style="info" %} Automation Activity

View execution history:

1. Go to Account Settings → Automations → Execution Log

2. Filter by folder or automation type

3. See success/failure details for each execution {% endhint %} {% endstep %} {% endstepper %}

---

Template Variables

Use these variables in title and description templates:

Item Information

Variable	Description	Example
{{item.title}}	Recording or capture title	"Checkout crashes"
{{item.url}}	Link to recording/capture	Full HTTPS URL
{{item.type}}	Item type	"recording" or "capture"
{{item.duration}}	Length in seconds	"45"
{{item.created_at}}	Submission timestamp	"Feb 6, 2026 at 2:30 PM"

Creator Information

Variable	Description	Example
{{creator.name}}	Person who submitted	"Alice Johnson"
{{creator.email}}	Creator's email	"[email protected]"

Recording-Specific (if applicable)

Variable	Description	Example
{{recording.title}}	Recording title	"Checkout page error"
{{recording.url}}	Recording link	Full HTTPS URL
{{recording.browser}}	Browser info	"Chrome 121.0.6167"
{{recording.os}}	Operating system	"macOS 14.3"
{{recording.resolution}}	Screen resolution	"2560x1440"
{{recording.country}}	Geographic location	"United States"
{{recording.console_errors}}	JavaScript errors	Formatted list
{{recording.network_errors}}	Failed HTTP requests	Formatted list

Capture-Specific (if applicable)

Variable	Description	Example
{{capture.title}}	Capture title	"Bug description"
{{capture.url}}	Capture link	Full HTTPS URL
{{capture.type}}	Capture type	Screenshot or document type

Folder & Account

Variable	Description	Example
{{folder.name}}	Folder name	"Bug Reports"
{{account.name}}	Workspace name	"Acme Corp"

View complete variable reference →

---

Example Configurations

Example 1: Bug Report Automation

Folder: Bug Reports Target: Report customer bugs to engineering team

Configuration:

Setting	Value
Team	Engineering
Project	Bug Fixes
Status	Backlog
Priority	Medium (P2)
Labels	from-screendesk, bug, customer-reported
Assignee	Unassigned

Title Template:

🐛 {{item.title}}

Description Template:

## Customer Bug Report

A customer submitted a recording describing this issue.

**Reported by:** {{creator.email}} ({{creator.name}})
**Folder:** {{folder.name}}

### Description
{{item.title}}

### Watch Recording
[View on Screendesk]({{item.url}})

---

### System Information
| Property | Value |
|----------|-------|
| Browser | {{recording.browser}} |
| Operating System | {{recording.os}} |
| Resolution | {{recording.resolution}} |
| Location | {{recording.country}} |
| Duration | {{recording.duration}} seconds |
| Submitted | {{recording.created_at}} |

### Technical Details

**Console Errors:**

{{recording.console_errors}}

**Network Errors:**

{{recording.network_errors}}

---

This issue was automatically created from a customer recording on Screendesk.

Result: Issues created with full bug context, ready for engineer triage and investigation.

---

Example 2: Feature Request Automation

Folder: Feature Requests Target: Track customer feature suggestions for product team

Configuration:

Setting	Value
Team	Product
Project	Feature Requests
Status	Backlog
Priority	No Priority
Labels	from-screendesk, feature-request, customer-feedback
Assignee	Product Manager

Title Template:

💡 Feature Request: {{item.title}}

Description Template:

## Customer Feature Request

A customer has requested the following feature.

**Suggested by:** {{creator.name}} ({{creator.email}})
**Folder:** {{folder.name}}

### Feature Description
{{item.title}}

### Customer Recording
[View feature request on Screendesk]({{item.url}})

**Recording Duration:** {{recording.duration}} seconds

---

This feature request was automatically created from a customer recording.

Result: Feature requests flow directly to product team for evaluation and roadmap planning.

---

Example 3: Critical Issue Automation (High Priority)

Folder: Critical Issues Target: Escalate urgent problems to on-call engineer immediately

Configuration:

Setting	Value
Team	Engineering
Project	Production Incidents
Status	Todo
Priority	Urgent (P0)
Labels	from-screendesk, urgent, critical, customer-impacting
Assignee	On-Call Engineer

Title Template:

🚨 CRITICAL: {{item.title}}

Description Template:

## CRITICAL ISSUE ALERT

A critical production issue has been reported.

**Reported by:** {{creator.email}} ({{creator.name}})

### Issue Details
{{item.title}}

### Watch Recording
[View Screendesk Recording]({{item.url}})

---

**IMMEDIATE ACTION REQUIRED**

This issue requires investigation as soon as possible.

**Timeline:**
* Submitted: {{recording.created_at}}
* Severity: CRITICAL (P0)

**Browser:** {{recording.browser}}
**OS:** {{recording.os}}
**Customer Location:** {{recording.country}}

---

[Assigned to: On-Call Engineer]

Result: Critical issues immediately become high-priority P0 tickets assigned to on-call engineers.

---

Example 4: Support Escalation Automation

Folder: Escalations Target: Create tickets when support team escalates customer issues

Configuration:

Setting	Value
Team	Engineering
Project	Customer Support
Status	Todo
Priority	High (P1)
Labels	from-screendesk, support-escalation, needs-triage
Assignee	Engineering Lead

Title Template:

[ESCALATED] {{item.title}} - Customer: {{creator.email}}

Description Template:

## Support Escalation

The support team has escalated this issue from a customer.

**Customer:** {{creator.name}} ({{creator.email}})
**Escalated at:** {{item.created_at}}

### Customer Issue
{{item.title}}

### Supporting Evidence
[View Recording]({{item.url}})

**Duration:** {{recording.duration}} seconds
**Browser:** {{recording.browser}}
**OS:** {{recording.os}}

---

This customer has been waiting for resolution. Please prioritize.

Result: Support escalations create high-priority tickets that go directly to engineering leads.

---

Bi-Directional Sync Features

Sync-Enabled Features

Once an issue is created from a recording, the following updates sync between Screendesk and Linear:

Synced from Linear to Screendesk:

• Issue status changes (Backlog → Todo → In Progress → Done)

• Issue comments from Linear team members

• Issue resolution status

• Priority changes

• Label additions/removals

Synced from Screendesk to Linear:

• New comments on the recording

• Recording tags and labels

• Recording status updates

How Bi-Directional Sync Works

1. Initial Creation — Automation creates Linear issue from recording

2. Link Established — Screendesk maintains reference to Linear issue

3. Status Sync — Changes propagate every 5 minutes

4. Comments Sync — Team discussions stay in sync

5. Resolution — When issue closes in Linear, recording shows as addressed

Enable Sync Features

Bi-directional sync is enabled by default for all Linear automations.

To verify sync is working:

1. Go to Account Settings → Integrations → Linear

2. Look for Bi-Directional Sync toggle

3. Ensure it's enabled (green)

In the recording: You'll see a "Linear Issue" section showing:

• Issue ID (e.g., "ENG-123")

• Issue title

• Current status

• Link to Linear

• Recent comments

Troubleshoot Sync Issues

If sync isn't working:

1. Check Linear connection — Ensure Linear is still connected in settings

2. Verify permissions — OAuth token needs read/write access

3. Check token expiration — Expired tokens prevent sync

4. Wait 5 minutes — Sync runs on 5-minute intervals

5. Refresh manually — Click the refresh icon in the Linear Issue panel

---

Cycle and Milestone Assignment

Add Issues to Current Cycle

Automatically include issues in the current Linear cycle:

Configuration:

1. Edit the automation

2. Look for Add to Current Cycle option

3. Toggle Enabled

4. Save

Result: New issues will automatically be added to your team's active cycle, making them visible in sprint planning and cycle progress.

When to use:

• Bug fix cycles

• Sprint-aligned feature work

• Urgent issues that need immediate scheduling

Assign to Specific Milestones

Link issues to project milestones:

Configuration:

1. Edit the automation

2. Find Milestone dropdown

3. Select a milestone

4. Save

Available milestones:

• All active milestones in your Linear team

• Issues will be linked to the selected milestone

• Milestone progress automatically includes these issues

When to use:

• Product launch features

• Release-specific bug fixes

• Long-term initiative tracking

---

Duplicate Prevention

Prevent creating multiple issues for the same problem:

By Customer Email

Configuration:

1. Edit the automation

2. Enable Prevent Duplicates

3. Select By Customer Email

4. Set time window (default: 24 hours)

5. Save

How it works:

• Same customer within 24 hours → No duplicate issue created

• Different customers → Issues created independently

• After 24 hours → Customer can create new issues

Use case: Prevent duplicate issues from the same user submitting multiple recordings.

By Recording Title

Configuration:

1. Edit the automation

2. Enable Prevent Duplicates

3. Select By Title

4. Set time window (default: 24 hours)

5. Save

How it works:

• Similar titles within 24 hours → No duplicate issue created

• Exact title match → Duplicate detected

• Title variations → Treated as separate issues

Use case: Prevent multiple issues for the same bug reported by different customers.

---

Managing the Integration

View Integration Status

Check Linear connection status:

1. Go to Account Settings

2. Select Integrations & Automations

3. Find Linear in the integrations list

4. See connection status and team information

Displayed information:

• Connection status (Connected/Disconnected)

• Team name and ID

• Team member count

• Last sync status

• Expiration warning (if token is expiring soon)

Disconnect Linear

Remove the Linear integration:

1. Go to Account Settings → Integrations & Automations

2. Find Linear

3. Click Disconnect

4. Confirm disconnection

What happens:

• All Linear automations are disabled (not deleted)

• Existing issues in Linear remain unchanged

• Sync stops immediately

• Automations can be re-enabled by reconnecting

Refresh Permissions

If Linear resources aren't loading:

1. Go to Account Settings → Integrations & Automations

2. Find Linear

3. Click Refresh

4. Re-authorize if prompted

5. Teams and projects update immediately

When to refresh:

• New projects created in Linear

• New team members added

• New labels created

• Permissions changed

Check Token Expiration

Linear tokens expire and need renewal:

1. Check Account Settings → Integrations & Automations

2. Look for expiration warning on Linear card

3. If expired: Click Reconnect button

4. Follow OAuth flow again

Automatic refresh: Screendesk automatically attempts to refresh tokens every 7 days. If this fails, you'll see a warning.

---

Troubleshooting

Issues Not Creating

Symptom: Automations enabled but no issues appear in Linear

Solutions:

{% stepper %} {% step %}

Verify Linear is connected

1. Go to Account Settings → Integrations & Automations

2. Check Linear status shows "Connected"

3. If disconnected, click Connect Linear to re-authorize {% endstep %}

{% step %}

Check team permissions

1. In Linear, verify your user has admin or owner role

2. Verify you have "Create Issues" permission

3. Check the selected team has active members

4. Try selecting a different team {% endstep %}

{% step %}

Verify automation is enabled

1. Open folder Settings → Automations

2. Find the Linear automation

3. Toggle should be green (on)

4. If disabled, click to enable {% endstep %}

{% step %}

Check execution logs

1. Go to Account Settings → Automations → Execution Log

2. Filter by the folder or automation

3. Look for error messages explaining why issue creation failed

4. Recent failures show detailed error information {% endstep %}

{% step %}

Test with a test issue

1. Open the automation

2. Click Create Test Issue

3. If test fails, error message explains why

4. Fix the issue and test again

{% hint style="info" %} Test issues show specific error messages that help diagnose problems. {% endhint %} {% endstep %} {% endstepper %}

Missing or Incorrect Fields

Symptom: Linear issue created but fields are empty or wrong

Solutions:

{% stepper %} {% step %}

Verify template syntax

Check title and description templates:

• Variables must be enclosed in double braces: {{variable}}

• Variable names must be spelled exactly

• No extra spaces or special characters

Correct: {{item.title}} Incorrect: {{ item.title }} or {{item.Title}} {% endstep %}

{% step %}

Check data availability

Some variables only exist for certain item types:

• {{recording.*}} — Only for recordings

• {{capture.*}} — Only for captures

• {{creator.*}} — Available for all items

If a recording doesn't have console errors, {{recording.console_errors}} will be empty. {% endstep %}

{% step %}

Test with sample data

Create a test recording/capture with the data you're referencing:

1. Add test item to folder

2. Create test issue

3. View the result

4. Adjust templates based on what's missing {% endstep %} {% endstepper %}

Wrong Team or Project

Symptom: Issue created in wrong team or project

Solutions:

1. Open the automation settings

2. Verify Team dropdown shows correct team

3. Verify Project dropdown shows correct project

4. Click Save to update

5. Create a test issue to verify

Note: Changes only affect new issues, not previously created ones.

Labels Not Applied

Symptom: Issue created but labels are missing

Solutions:

{% stepper %} {% step %}

Verify labels exist in Linear

1. Open Linear workspace

2. Go to team settings → Labels

3. Check that your configured labels exist

4. Labels must be created in Linear before using in Screendesk {% endstep %}

{% step %}

Refresh label list in Screendesk

1. Go to Account Settings → Integrations & Automations

2. Find Linear

3. Click Refresh

4. Wait for labels to update

5. Edit automation and verify labels appear {% endstep %}

{% step %}

Re-add labels to automation

1. Open the automation settings

2. Remove old labels

3. Click + Add Label to re-select

4. Choose labels from the refreshed list

5. Save and test {% endstep %} {% endstepper %}

Assignee Not Applied

Symptom: Issue not assigned to selected team member

Solutions:

1. Verify the selected person is active in Linear

2. Inactive members can't be assigned

3. Go to Linear team settings → Members

4. Check if the person is still active

5. If inactive, select a different assignee

Token Expired

Symptom: "Linear access token has expired" error

Solutions:

1. Go to Account Settings → Integrations & Automations

2. Look for expiration warning on Linear card

3. Click Reconnect

4. Follow the OAuth authorization flow

5. Return to Screendesk and test

Prevention: Screendesk automatically refreshes tokens. If refresh fails, you'll see a warning before token expires.

Sync Not Working

Symptom: Linear issue changes don't appear in Screendesk recording

Solutions:

{% stepper %} {% step %}

Verify sync is enabled

1. Go to Account Settings → Integrations → Linear

2. Look for Bi-Directional Sync toggle

3. Ensure it's enabled (green)

4. If disabled, enable it and save {% endstep %}

{% step %}

Check token is valid

1. If token expired, reconnect Linear (see Token Expired above)

2. Expired tokens prevent sync

3. After reconnecting, sync resumes automatically {% endstep %}

{% step %}

Wait for sync cycle

Sync runs every 5 minutes:

1. Make a change in Linear

2. Wait up to 5 minutes

3. Refresh the Screendesk recording page

4. Changes should appear

Don't worry if sync takes up to 5 minutes. {% endstep %}

{% step %}

Check for webhook issues

1. Go to Account Settings → Automations → Execution Log

2. Look for sync-related entries

3. Check for error messages

4. If webhooks failed, sync may be delayed {% endstep %} {% endstepper %}

Slow Issue Creation

Symptom: Issues take longer than expected to be created

Solutions:

1. Check Linear API status — Visit Linear Status Page

2. Verify internet connection — Ensure stable connection to screendesk.io and linear.app

3. Check automation logs — View execution timestamps to identify delays

4. Try again — If a temporary issue, retry with a new recording

Typical creation time: 5-30 seconds. Longer delays indicate network or API issues.

Rate Limiting

Symptom: "Rate limit exceeded" error

Solutions:

1. Wait before retrying — Linear enforces rate limits; wait a few minutes

2. Space out automations — Don't trigger many automations simultaneously

3. Check documentation — Linear API has rate limits; see Linear Docs

4. Contact Linear support — If limits are too restrictive for your use case

OAuth Authorization Failed

Symptom: "Linear authorization failed" error during connection

Solutions:

1. Verify Linear credentials — Ensure client ID/secret are correct

2. Check OAuth scope — "write" scope is required

3. Verify redirect URI — Must match configured callback URL

4. Try again — Click Connect Linear to retry

If issues persist, contact Screendesk support.

Check Automation Logs

View detailed execution history:

1. Go to Account Settings → Automations

2. Click Execution Log tab

3. Filter by folder or automation type

4. Click any log entry to see details

Log information includes:

• Timestamp of execution

• Success or failure status

• Error message (if failed)

• Issue ID created (if successful)

• Time taken to execute

---

Best Practices

Use Consistent Naming

Keep naming conventions consistent:

{% columns %} {% column %} ❌ Inconsistent:

bug: checkout error
BUG - login failing
Customer says: password reset broken
[SEV-1] database timeout

{% endcolumn %}

{% column %} ✅ Consistent:

🐛 Checkout page error
🐛 Login failing
🐛 Password reset broken
🐛 Database timeout

{% endcolumn %} {% endcolumns %}

Consistent naming makes issues easier to scan and search in Linear.

---

Set Appropriate Priority Levels

Match folder urgency to issue priority:

Folder	Recommended Priority
General Feedback	No Priority
Bug Reports	Medium (P2)
Feature Requests	No Priority
Critical Issues	Urgent (P0)
Support Escalations	High (P1)

Don't over-prioritize. Let your team adjust based on actual impact.

---

Use Meaningful Labels

Create labels for quick filtering:

Organizational labels:

• from-screendesk — Track all automated issues

• customer-reported — Issues from customers

• internal-report — Issues from your team

Type labels:

• bug, feature-request, enhancement, documentation

• performance, security, ui, backend

Status labels:

• needs-triage, blocked, duplicate

• critical, high-priority, low-priority

Apply 2-4 labels per issue for effective organization.

---

Include Recording Links Prominently

Make accessing customer evidence easy:

{% columns %} {% column %} ❌ Buried:

This is a bug report.
See details below.
...lots of text...
Link: {{item.url}}

{% endcolumn %}

{% column %} ✅ Prominent:

[View Recording]({{item.url}})

**Description:**
{{item.title}}

{% endcolumn %} {% endcolumns %}

Put the recording link near the top where engineers will see it first.

---

Add Environment Context

Include technical details for debugging:

**System Information**
| Property | Value |
|----------|-------|
| Browser | {{recording.browser}} |
| OS | {{recording.os}} |
| Resolution | {{recording.resolution}} |
| Location | {{recording.country}} |

This helps engineers reproduce issues and understand scope.

---

Enable Duplicate Prevention

Reduce spam and noise:

• For Bug Folders — Prevent by customer email (24 hours)

• For Feature Requests — Prevent by title (24 hours)

• For General — Consider disabling if high volume

Duplicate prevention prevents the same issue from being created multiple times.

---

Test Before Large Deployment

Before creating many automations:

1. Create one automation

2. Add a test recording

3. Verify in Linear

4. Check title, description, labels, priority

5. Adjust templates as needed

6. Then create additional automations

Testing first saves time fixing issues later.

---

Create Folder Hierarchies

Organize your folders by automation type:

Root
├── Bug Reports
│   ├── Critical Bugs (P0 automation)
│   ├── Customer Bugs (P2 automation)
│   └── Internal Bugs (P3 automation)
├── Feature Requests
│   ├── High Priority
│   └── General Feedback
└── Support
    ├── Escalations
    └── General Inquiries

Folder hierarchies let you create targeted automations for different priorities.

---

Monitor Automation Success Rate

Regularly check execution logs:

1. Go to Account Settings → Automations → Execution Log

2. Filter by Linear automations

3. Look for patterns in failures

4. Address common issues

Target success rate: 99%+

---

Use Distribution Cycles

Distribute new issues across your team:

• Create multiple automations targeting different assignees

• Rotate which automation receives recordings

• Ensures fair work distribution

• Prevents bottlenecks

---

Document Your Setup

Keep notes on your automations:

• Why each automation exists

• What folder triggers it

• Where issues go in Linear

• Who manages it

This helps new team members understand the system.