Skip to main content
Integrating Linear with Vistaly helps align product strategy with delivery execution. When Linear issues and projects are connected to Vistaly cards, teams can see the full context of why their work matters to customers and the business, while product leaders can track delivery progress alongside strategic outcomes.

​
Key Benefits

  • See strategy and delivery in one place: View Linear project and issue progress directly on your roadmap cards, connecting strategic outcomes with engineering execution
  • Connect work to customer impact: Engineering teams can trace their Linear issues back to the customer problems and business outcomes they’re addressing
  • Bidirectional sync: Create and update Linear issues and projects from Vistaly, and changes flow both ways to keep teams aligned
  • Smart search and linking: Find and link Linear issues or projects using native Linear search, or paste Linear URLs for instant connections
  • Progress visibility: Track Linear project completion percentage and issue status directly on Vistaly card faces in the roadmap view

​
Installing the Linear Integration

To install the Linear integration, visit the integrations page in Vistaly and select ‘Add to Linear’.
Integrations page with Linear option
 You’ll be redirected to Linear to authorize Vistaly’s access to your workspace. After authorization, select which Linear teams you want to connect to your Vistaly organization. Once connected, you’ll see a Linear tab appear on your Vistaly cards where you can link issues and projects.

​
Linking Linear Issues to Vistaly Cards

You can link Linear issues to any card type in Vistaly - Solutions, Opportunities, Outcomes, or any other card where you want to track delivery work.

​
Creating a New Linear Issue

  1. Open a Vistaly card and select the Linear tab
  2. Click “Create & Link Issue”
  3. Choose your Linear team
  4. Fill in the issue details:
    • Title (pre-populated from your card)
    • Description (can be AI-enhanced based on card context)
    • Priority
    • Assignee
    • Status
    • Labels
    • Parent project (optional)
  5. Click “Create Issue”
Creating a new Linear issue
 The issue is created in Linear and automatically linked to your Vistaly card. The Linear team selection is remembered for faster workflow next time.

​
Linking an Existing Linear Issue

You have two ways to link existing Linear issues: Option 1: Search
  1. Open the Linear tab on a Vistaly card
  2. Click “Link Existing Issue”
  3. Search for your issue using Linear’s native search
  4. Select the issue from search results
Searching for Linear issues
 Option 2: Paste URL
  1. Copy a Linear issue URL from your browser
  2. Open the Linear tab on a Vistaly card
  3. Click “Link Existing Issue”
  4. Paste the Linear URL
  5. The issue is automatically detected and linked

​
Updating Linear Issues from Vistaly

Once linked, you can update Linear issue properties directly from Vistaly:
  • Status: Change workflow state using available Linear states
  • Priority: Update priority level (No priority, Urgent, High, Medium, Low)
  • Assignee: Assign or reassign team members
  • Labels: Add or remove Linear labels
  • Project: Move the issue to a different Linear project
All updates sync immediately to Linear.

​
Linking Linear Projects to Vistaly Cards

Linear projects are ideal for tracking larger initiatives connected to Outcomes or Opportunities in Vistaly.

​
Creating a New Linear Project

  1. Open a Vistaly card and select the Linear tab
  2. Click “Create & Link Project”
  3. Fill in the project details:
    • Name (pre-populated from your card)
    • Description
    • Lead
    • Teams
    • Priority
    • Status
    • Start date and target date
  4. Click “Create Project”
Creating a new Linear project
 The project is created in Linear with all your settings and immediately linked to your Vistaly card.

​
Linking an Existing Linear Project

Similar to issues, you can link existing projects by:
  1. Searching for the project name in the Linear tab
  2. Pasting a Linear project URL

​
Updating Linear Projects from Vistaly

Update project properties directly from Vistaly:
  • Status: Change project status (Backlog, Planned, Started, Paused, Completed, Canceled)
  • Priority: Set project priority
  • Lead: Assign a project lead
  • Dates: Update start date and target date
Changes sync immediately to Linear.

​
Viewing Progress in the Roadmap

One of the most powerful features of the Linear integration is seeing delivery progress directly on your roadmap.
Linear progress displayed on roadmap cards

​
Linear Project Progress

When a Linear project is linked to a card, the project’s completion percentage appears on the card face in the roadmap view. This allows product leaders to:
  • See at a glance which initiatives are on track
  • Identify projects that need attention
  • Understand delivery velocity across your product portfolio
  • Connect strategic outcomes to engineering execution

​
Linear Issue Status

Linked Linear issues display their current status on Vistaly cards, helping teams:
  • Track solution delivery progress
  • Understand what’s in progress vs. completed
  • See workflow state without leaving Vistaly

​
Bi-directional Sync and Context

​
From Vistaly to Linear

When you create a Linear issue or project from Vistaly, Linear cards automatically include a link back to the Vistaly card. This gives engineering teams one-click access to:
  • The customer problems being solved
  • Related customer feedback and research
  • Strategic outcomes this work contributes to
  • Success metrics and how this work will be measured

​
From Linear to Vistaly

Status changes, progress updates, and metadata changes in Linear automatically sync to Vistaly, ensuring:
  • Stakeholders see current progress without asking for updates
  • Product roadmaps reflect real delivery status
  • Strategic discussions are grounded in execution reality

​
AI-Powered Description Enhancement

When creating Linear issues from Vistaly, you can use AI to generate comprehensive issue descriptions based on your card’s content:
  1. Click “Create & Link Issue”
  2. Select “Enhance with AI” in the description field
  3. AI analyzes your card context (including linked customer feedback, parent cards, and related content)
  4. A detailed description is generated, including:
    • Problem context
    • Success criteria
    • Related customer insights
    • Implementation considerations
This helps ensure engineering teams have full context without manual copy-pasting.

​
Multiple Linear Issues per Card

You can link multiple Linear issues to a single Vistaly card, which is useful for:
  • Breaking down large Solutions into multiple implementation issues
  • Tracking work across different Linear teams
  • Managing phased delivery approaches
  • Connecting related technical work to the same strategic goal

​
Search Capabilities

The Linear integration supports powerful search:
  • Full-text search: Find issues and projects by title, identifier, or description
  • Multi-team search: Search across all connected Linear teams
  • URL detection: Automatically detect and link when you paste Linear URLs
  • Real-time results: Search results update as you type

​
Best Practices

​
When to Use Linear Projects vs. Issues

Based on how teams are using the Linear integration:
  • Use Linear Projects for:
    • Opportunities - Large customer problems or needs that span multiple solutions
    • Large Solutions - Complex features that require multiple issues to implement
    • Multi-sprint initiatives that involve coordination across the team
    • Work that breaks down into multiple smaller deliverables
  • Use Linear Issues for:
    • Solutions - Individual features and improvements that deliver customer value
    • Specific implementation tasks that can be completed within a sprint or two
Tracking Maintenance and Technical Debt: Bugs, technical debt, and “keeping the lights on” work are typically managed entirely in Linear. However, some teams create a “Maintenance” or “Non-Strategic Work” bucket in Vistaly and link these issues there. This allows you to visualize:
  • How much time and energy is spent on strategic vs. non-strategic work
  • The balance between new features and maintenance
  • Where engineering capacity is actually going
This visibility helps product leaders make informed decisions about resource allocation and technical debt prioritization.

​
Organizing Your Integration

  • Link Linear projects to Opportunities or large Solutions - This helps track the bigger customer problems and complex features you’re addressing
  • Link Linear issues to Solutions - Connect individual features and improvements to track their delivery progress
  • Use Vistaly’s roadmap view to see both strategy and delivery status together
  • Keep project and issue status current to maintain accurate progress visibility on your roadmap
  • Consider linking multiple Linear issues to a single Solution when breaking down complex work

​
Communication and Alignment

  • Share roadmap views with stakeholders to show strategy + progress
  • Use Linear’s back-link to Vistaly to give engineers strategic context
  • Update Linear project status regularly to keep roadmap views accurate
  • Connect customer feedback in Vistaly to show engineers the “why” behind their work

​
Troubleshooting

​
Linear Integration Not Appearing

If you don’t see the Linear tab on your cards:
  1. Check that the Linear integration is installed on your organization’s integrations page
  2. Ensure you have editor privileges in the Vistaly workspace
  3. Try refreshing the page

​
Issues or Projects Not Syncing

If changes aren’t appearing:
  1. Check your internet connection
  2. Verify you have appropriate permissions in Linear
  3. Refresh the Vistaly page to see latest updates
  4. Check Linear’s API status if issues persist

​
Permission Issues

If you can’t create or update Linear items:
  1. Verify your Linear workspace permissions
  2. Ensure the Linear integration has the necessary scopes
  3. Try reconnecting the integration from the settings page

​
Learn More