Linear Integration

This guide explains how to connect Linear to Supervity, what data is available after connection, how operators can use Linear data and actions within workflows, and how to remove the integration when needed.

---

Overview

The Supervity Linear integration allows your workspace to securely connect Linear as a governed platform capability.

Once connected, operators and workflows can use Linear data and actions to automate software project management, streamline issue tracking, manage team workflows, update issue statuses, and coordinate development tasks across connected systems.

With the Linear integration, Supervity can:

• Retrieve authenticated user details to verify connection identity
• Access workspace teams and team identifiers
• Retrieve workspace members and user profiles
• List workflow states and custom issue statuses across teams
• Query and filter issues by team and status with pagination support
• Create new issues with team assignment, descriptions, assignees, and workflow states
• Update existing issues by modifying their status or reassigning them
• Add comments and updates to issues
• Use Linear issue tracking and project data as context for operators
• Trigger workflows based on issue creation, updates, and status transitions

All Linear access is governed through Supervity's security, permissions, and audit controls.

---

Prerequisites

Before connecting Linear, ensure you have:

• An active Supervity workspace
• A Linear account with access to the target workspace
• Permission to authorize third-party OAuth applications in Linear
• Membership in the teams and projects containing the issues you want to manage

Depending on your Linear workspace settings, administrative approval may be required before third-party applications can access workspace resources.

---

Adding the Linear Integration

Follow these steps to connect Linear to Supervity. If you encounter any issues during setup, refer to the Troubleshooting section of this guide.

Step 1: Open Integrations

1. Log in to Supervity.
2. From the left navigation bar, click the Integrations icon.

This opens the Integrations page, where all available integrations are listed. Connected integrations and available integrations can both be managed from this page.

Step 2: Select Linear

1. Locate Linear in the available integrations list.
2. Click Connect.

Step 3: Authorize Access

You will be redirected to Linear's secure authorization page.

Review the requested permissions and click Authorize (or Allow) to grant Supervity access to your Linear workspace.

• Supervity uses Linear's standard OAuth 2.0 authorization flow.
• Your Linear password is never shared with or stored by Supervity.

Step 4: Complete Connection

After authorization, you will be redirected back to Supervity.

The Linear integration will appear as Connected on the Integrations page. Your workspace can now securely access Linear capabilities according to the permissions granted.

Having trouble? See the Troubleshooting section for step-by-step help with common setup issues.

---

How Linear Works in Supervity

After connection, Linear becomes available as a governed platform tool.

Operators can use Linear capabilities when planning and executing tasks, while workflows can automate actions using Linear project and issue data.

Common use cases include:

• Creating issues automatically from customer support tickets, error monitors, or incident alerts
• Updating issue progress and workflow states when code is deployed or verified
• Assigning issues to team members based on workload or topic expertise
• Adding automated progress notes or context comments to Linear tickets
• Retrieving active sprint backlog issues for status reporting and stand-up summaries
• Synchronizing Linear tasks with external roadmaps, CRM systems, or messaging platforms

---

Using Linear in Operators

Connected Linear capabilities become available to operators automatically. Operators determine when Linear data or actions are required to complete a task and execute accordingly, while remaining governed by workspace permissions, security controls, and approval policies.

What Operators Can Do with Linear

Operators can perform the following actions using Linear:

• View authenticated viewer profile details
• Retrieve active teams and workspace members
• List team workflow states and progression statuses
• Query and filter issues by team and criteria with pagination support
• Create issues with titles, descriptions, assignees, and workflow states
• Update issue statuses or reassign them to team members
• Post discussion comments and updates to specific issues
• Correlate Linear tasks with monitoring tools, code repositories, CRM records, and chat applications
• Generate summaries, release changelogs, and sprint completion reports from issue records
• Combine issue tracking actions with other connected applications for automated workflows

Typical Operator Use Cases

---

Features & Prerequisites

For each Linear capability available in Supervity, the following describes the use case and the prerequisites required before use.

Get Authenticated User

Use Case: Fetch the authenticated user profile (viewer) details to verify active credentials and connection identity.

Prerequisites:

• Linear account connected to Supervity

---

List Teams

Use Case: Retrieve a list of active teams in the workspace, including team names, identifiers, and keys. Useful for selecting target teams when routing or creating issues.

Prerequisites:

• Linear account connected to Supervity
• Read permissions enabled for workspace teams

---

List Users

Use Case: Retrieve workspace members to find user identifiers, names, and emails for issue assignment and mention routing.

Prerequisites:

• Linear account connected to Supervity
• Read permissions enabled for workspace users

---

List Workflow States

Use Case: Retrieve workflow states (such as Backlog, Todo, In Progress, In Review, Done, Canceled) for teams across the workspace to validate and select valid status IDs.

Prerequisites:

• Linear account connected to Supervity
• Read permissions enabled for workflow states

---

List Issues

Use Case: Retrieve a paginated list of issues with optional filtering by team. Useful for inspecting team backlogs, tracking ticket statuses, and auditing active tasks.

Prerequisites:

• Linear account connected to Supervity
• Read permissions enabled for issues

---

Create Issue

Use Case: Programmatically create a new issue within a specified team, setting the title, detailed description, assignee, and initial workflow state.

Prerequisites:

• Linear account connected to Supervity
• Valid team ID, title, description, assignee ID, and state ID must be provided
• Write permissions enabled for issue creation

---

Update Issue

Use Case: Update an existing issue by modifying its workflow state (status) or reassigning it to another team member.

Prerequisites:

• Linear account connected to Supervity
• Target issue ID must exist
• Valid new state ID or assignee ID must be provided
• Write permissions enabled for issue modification

---

Create Comment

Use Case: Post a comment on an existing issue to provide updates, add automated logs, or communicate status changes.

Prerequisites:

• Linear account connected to Supervity
• Target issue ID must exist
• Comment body text must be provided
• Write permissions enabled for comment creation

---

Permissions Requested

Supervity only requests the permissions required for enabled Linear capabilities.

Depending on the features used in your workspace, permissions may include:

Supervity follows least-privilege principles and only accesses data necessary to provide requested functionality.

---

Authentication & Security

The Linear integration uses OAuth 2.0 authentication.

Security controls include:

• Encrypted credential storage (AES-256)
• Least-privilege access scopes
• Token refresh and rotation support
• Immediate revocation capabilities
• Workspace-level governance controls
• Complete audit logging
• TLS 1.3 for all API and UI connections

All Linear access remains subject to Supervity security policies and role-based permissions.

---

Managing the Integration

View Connection Status

From the left navigation bar, click the Integrations icon.

For Linear you can view:

• Connection status
• Granted permissions
• Last usage information
• Associated workflows and operators

Reconnect Linear

If Linear authorization expires or permissions change:

1. Open the Integrations page from the left navigation bar.
2. Select Linear.
3. Click Reconnect.
4. Complete authorization again through the Linear portal.

Existing workflows and operators do not need to be recreated.

Removing the Linear Integration

You can remove the Linear connection from your Supervity workspace at any time directly from within the Supervity platform.

Steps to Remove

1. Log in to Supervity.
2. From the left navigation bar, click the Integrations icon.
3. Locate and select Linear from the integrations list.
4. Click Disconnect.
5. Confirm the action when prompted.

Implications of Removal

Once removed:

• Supervity immediately loses all access to your Linear workspace and associated data
• No new Linear data will be retrieved or modified after removal
• All active Linear connections within your Supervity workspace are terminated
• Scheduled or active workflows that depend on Linear will stop executing
• Linear-dependent workflow steps will fail safely with clear error messages
• Existing workflow definitions within Supervity are not deleted — only the active connection is terminated
• Historical execution logs remain available for auditing purposes

Disconnecting Linear does not delete workflow definitions, operators, or previously generated outputs.

How Your Data Is Handled After Removal

Data Handling on Removal:

• Supervity immediately loses access to your Linear workspace upon removal
• No new Linear issues, comments, or data will be collected or processed after disconnection
• Temporary files processed during workflow execution are deleted after execution completes
• Linear access tokens and all account-related data are permanently deleted from Supervity's platform within 15 minutes of disconnection — no background access continues after removal

---

Auditing & Observability

All Linear activity performed through Supervity is logged.

Audit records include:

• Which operator requested access
• Which workflow executed the action
• Timestamp of execution
• Success or failure status
• Relevant inputs and outputs (sensitive values are redacted)

This supports compliance, troubleshooting, governance, and operational visibility.

---

Troubleshooting

If you encounter issues at any stage, refer to the steps below. For issues not covered here, contact the Supervity support team.

Authorization Failed During Setup

Likely Cause: Incorrect Linear account used, or workspace permissions restrict third-party OAuth app authorization.

Resolution:

1. Ensure you are signed in to the correct Linear workspace with permissions to authorize integrations.
2. Verify that third-party applications are permitted by your Linear workspace settings.
3. Return to Supervity → Integrations → Linear and click Connect to retry.
4. If the issue persists, contact your Linear workspace administrator.

---

Linear Shows Connected but Issues Are Missing

Likely Cause: Issues belong to a team or private project that the connected user account cannot access.

Resolution:

1. Confirm that the authorized user has membership and access rights to the target team in Linear.
2. Check that the team filter matches the team ID.
3. Reconnect the integration via Integrations → Linear → Reconnect to refresh permissions.

---

Connection Expired or Token Invalid

Likely Cause: OAuth token expired or was revoked in Linear settings.

Resolution:

1. Go to Integrations → Linear → Reconnect.
2. Complete the Linear authorization flow again.
3. Existing workflows do not need to be reconfigured after reconnection.

---

Workflow Cannot Access Linear

Likely Cause: Linear may have been disconnected, or workspace governance policies may restrict access.

Resolution:

1. Confirm Linear is still connected under the Integrations page.
2. Verify the workflow has permission to use Linear within your workspace governance settings.
3. Check that workspace policies allow Linear execution for the relevant operators or workflows.

---

Issue Creation Fails

Likely Cause: Missing required parameters (such as team ID, title, description, assignee ID, or state ID) or invalid identifiers.

Resolution:

1. Verify that a valid team ID is provided.
2. Ensure the state ID corresponds to a valid workflow state for that specific team (retrieve valid state IDs via list_workflow_states).
3. Check that the assignee ID belongs to an active member of the workspace.

---

Updating Issue Status Fails

Likely Cause: Invalid issue ID or attempting to assign a workflow state that does not belong to the issue's team.

Resolution:

1. Verify the target issue ID exists in Linear.
2. Confirm the state ID belongs to the same team that owns the issue.
3. Ensure the connected account has edit permissions for that team's issues.

---

Frequently Asked Questions

Q: Is my Linear password shared with or stored by Supervity?

No. Supervity uses Linear's standard OAuth 2.0 authorization flow. Your Linear password is never shared with or stored by Supervity. Only scoped access tokens are stored, and these are encrypted at rest using AES-256.

---

Q: Can I create issues across multiple teams?

Yes. When creating an issue, you specify the target team ID. As long as the authorized user account has access to that team, Supervity can create and manage issues across multiple teams in your workspace.

---

Q: Will I need to reconfigure my workflows after reconnecting Linear?

No. If you reconnect Linear due to token expiry or permission updates, existing workflow definitions and operators do not need to be recreated or reconfigured.

---

Q: What happens to my workflows if I disconnect or remove Linear?

Workflow definitions are not deleted when Linear is disconnected or removed. However, any workflow steps that depend on Linear will fail safely with clear error messages until Linear is reconnected.

---

Q: How do I authorize the Supervity Linear integration?

Log in to Supervity at Supervity, navigate to the Integrations page from the left navigation bar, locate Linear, and click Connect. You will be redirected to Linear's authorization page where you can review and approve the requested permissions. After authorization, you will be redirected back to Supervity automatically. See the Adding the Linear Integration section above for full step-by-step instructions.

---

Q: Who do I contact if I have an issue with the integration?

Contact the Supervity support team. See the Support section below for full contact details, support hours, and SLA information.

---

Support

If you need assistance with the Linear integration, visit the Support page.

Support Hours

• Monday to Friday, 9:00 AM – 6:00 PM IST
• Requests submitted outside business hours will be addressed on the next business day

First Response SLA

• All support requests receive an initial response within 24 business hours

Contact Information

When Contacting Support, Please Provide

• Workspace name
• Linear workspace name or user email used for authorization
• Relevant workflow or operator information
• Error messages or screenshots when available

This helps the support team investigate and resolve issues more quickly.

---

Related Documentation

• Integrations Overview
• OAuth2
• Security & Privacy
• Supervity Website