# 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

{% hint style="info" %}
**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
  {% endhint %}

***

### 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.

{% hint style="warning" %}
**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.
{% endhint %}

#### 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)

{% hint style="success" %}
**Connection Verified**

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

#### 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

{% hint style="info" %}
**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.
{% endhint %}

#### 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}}
```

{% hint style="warning" %}
**Title Length**

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

View all available template variables →

#### Configure issue description

Create a rich issue description with recording context:

**Default description template:**

```markdown
**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**

```markdown
## 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**

```markdown
## 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      | "<alice@customer.com>" |

#### 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:**

```markdown
## 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:**

```markdown
## 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:**

```markdown
## 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:**

```markdown
## 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](https://status.linear.app)
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](https://developers.linear.app/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:

```markdown
**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.