> ## Documentation Index
> Fetch the complete documentation index at: https://docs.civic.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Linear Server

> Streamline your workflow with Linear's issue tracking and project management tools

# Linear Server

## Overview

The Linear server provides comprehensive project management and issue tracking capabilities. Built by [Linear](https://linear.app), this server enables AI assistants to manage issues, coordinate projects, track sprints, and streamline development workflows.

## Getting Started

<Steps>
  <Step title="Connect to Linear">
    Add the Linear server to your Civic environment through the server directory.
  </Step>

  <Step title="Authenticate with Linear">
    Connect your Linear workspace using OAuth to access your teams and projects.
  </Step>

  <Step title="Test Connection">
    Start with `get user` to verify authentication and `list teams` to see your workspace structure.
  </Step>
</Steps>

## What You Can Do

<CardGroup cols={2}>
  <Card title="Issue Management" icon="list-check">
    Create, update, search, and track issues across teams and projects
  </Card>

  <Card title="Project Coordination" icon="folder-tree">
    Manage projects, assign leads, set timelines, and track progress
  </Card>

  <Card title="Team Organization" icon="users">
    Coordinate teams, workflows, and sprint cycles for efficient delivery
  </Card>

  <Card title="Workflow Automation" icon="arrows-spin">
    Automate issue creation, updates, and status transitions based on development events
  </Card>
</CardGroup>

## Use Cases

<AccordionGroup>
  <Accordion title="Issue Tracking & Management" icon="bug">
    * **Bug Reporting**: Create detailed bug reports with descriptions, priorities, and assignments
    * **Feature Requests**: Track feature development from concept to completion
    * **Task Management**: Organize development tasks with estimates and deadlines
    * **Status Tracking**: Monitor issue progress through customizable workflow states
  </Accordion>

  <Accordion title="Project Planning & Execution" icon="calendar">
    * **Project Setup**: Create projects with timelines, leads, and team assignments
    * **Sprint Planning**: Organize work into cycles with clear start and end dates
    * **Progress Monitoring**: Track project completion and identify blockers
    * **Resource Allocation**: Balance workload across team members and projects
  </Accordion>

  <Accordion title="Team Collaboration" icon="handshake">
    * **Cross-team Coordination**: Manage dependencies between different teams
    * **Communication**: Add comments and updates to issues for clear communication
    * **Assignment Management**: Distribute work based on expertise and availability
    * **Workflow Standardization**: Ensure consistent processes across teams
  </Accordion>

  <Accordion title="Development Integration" icon="code">
    * **Code-to-Issue Linking**: Connect code changes to specific Linear issues
    * **Automated Updates**: Update issue status based on Git commits and deployments
    * **Release Planning**: Organize issues into releases and track completion
    * **Quality Assurance**: Track testing, reviews, and deployment status
  </Accordion>
</AccordionGroup>

***

## Available Tools (26)

<AccordionGroup>
  <Accordion title="User & Team Management (3 tools)">
    Essential tools for understanding workspace structure and team organization.

    **Workspace Discovery**

    <AccordionGroup>
      <Accordion title="get_user">
        Get information about the authenticated Linear user and workspace access
      </Accordion>

      <Accordion title="list_teams">
        List all teams in the workspace with optional archived team inclusion

        * **Parameters**: includeArchived (boolean, default: false)
      </Accordion>

      <Accordion title="list_users">
        List all users in the workspace with activity status

        * **Parameters**: includeInactive (boolean, default: false)
      </Accordion>
    </AccordionGroup>

    <Info>
      **Team IDs**: Required for most operations - get them via `list_teams` first.
    </Info>
  </Accordion>

  <Accordion title="Issue Operations (5 tools)">
    Core functionality for creating, updating, and managing Linear issues.

    **Issue Lifecycle Management**

    <AccordionGroup>
      <Accordion title="search_issues">
        Advanced issue search with multiple filter options

        * **Filters**: query, teamId, projectId, assigneeId, state, limit (1-100)
        * **States**: backlog, todo, in\_progress, done, canceled
      </Accordion>

      <Accordion title="get_issue">
        Get detailed information about specific issues

        * **Input**: Issue ID or issue number (e.g., 'ENG-123')
      </Accordion>

      <Accordion title="create_issue">
        Create new issues with full metadata support

        * **Required**: title, teamId
        * **Optional**: description, projectId, assigneeId, priority (0-4), labelIds, estimate
      </Accordion>

      <Accordion title="update_issue">
        Update existing issues with flexible field modifications

        * **Updatable**: title, description, stateId, assigneeId, priority, labelIds, estimate
      </Accordion>

      <Accordion title="add_comment">
        Add markdown-formatted comments to issues for collaboration

        * **Parameters**: issueId (required), body (markdown format)
      </Accordion>
    </AccordionGroup>

    <Note>
      **Priority Levels**: 0=No priority, 1=Urgent, 2=High, 3=Normal, 4=Low
    </Note>
  </Accordion>

  <Accordion title="Project Management (3 tools)">
    Tools for organizing work into projects and tracking progress.

    <AccordionGroup>
      <Accordion title="list_projects">
        List projects with team and archive filtering

        * **Parameters**: teamId (optional), includeArchived (boolean, default: false)
      </Accordion>

      <Accordion title="create_project">
        Create new projects with timeline and team assignments

        * **Required**: name, teamIds (array)
        * **Optional**: description, leadId, targetDate, startDate (YYYY-MM-DD)
      </Accordion>

      <Accordion title="list_cycles">
        List sprint cycles for agile development

        * **Parameters**: teamId (required), includeCompleted (boolean, default: false)
      </Accordion>
    </AccordionGroup>

    <Tip>
      **Date Format**: Use ISO date format (YYYY-MM-DD) for startDate and targetDate parameters.
    </Tip>
  </Accordion>

  <Accordion title="Workflow & Configuration (3 tools)">
    Tools for managing workflow states, labels, and team configuration.

    <AccordionGroup>
      <Accordion title="list_workflows">
        Get workflow states and transitions for specific teams

        * **Parameters**: teamId (required)
        * **Use Cases**: Understand available states for issue updates
      </Accordion>

      <Accordion title="list_labels">
        List available labels for categorizing and organizing issues

        * **Parameters**: teamId (optional filter)
        * **Use Cases**: Get label IDs for issue creation and updates
      </Accordion>
    </AccordionGroup>

    <Warning>
      Always use `list_workflows` to get valid stateIds before updating issue states.
    </Warning>
  </Accordion>
</AccordionGroup>

***

## Configuration Requirements

### Authentication Setup

The Linear server uses OAuth2 authentication with Linear's API:

<AccordionGroup>
  <Accordion title="OAuth Scopes" icon="key">
    * **Read Access**: View issues, projects, teams, and user data
    * **Write Access**: Create and update issues, projects, and comments
    * **Workspace Access**: Access to all teams and projects in your workspace
  </Accordion>

  <Accordion title="Required Permissions" icon="shield-check">
    * **Team Member**: Must be a member of teams you want to manage
    * **Project Access**: View and edit permissions for relevant projects
    * **Issue Management**: Create, update, and comment permissions
    * **User Directory**: Access to workspace user list for assignments
  </Accordion>
</AccordionGroup>

## Best Practices

### Issue Management Workflow

1. **Team Discovery**: Use `list_teams` to understand workspace structure
2. **Issue Creation**: Use `create_issue` with appropriate team, priority, and labels
3. **Progress Tracking**: Use `search_issues` with state filters to monitor progress
4. **Status Updates**: Use `update_issue` to move issues through workflow states
5. **Communication**: Use `add_comment` for updates and collaboration

### Project Planning Best Practices

1. **Project Setup**: Use `create_project` with clear timelines and team assignments
2. **Sprint Organization**: Use `list_cycles` to plan work in iterations
3. **Workload Distribution**: Balance assignments using `list_users` and search filters
4. **Progress Monitoring**: Track project completion with filtered issue searches

### Workflow Optimization

1. **State Management**: Use `list_workflows` to understand available transitions
2. **Label Strategy**: Use `list_labels` to maintain consistent categorization
3. **Automation**: Create issues automatically based on errors, deployments, or events
4. **Integration**: Link issues to code commits, pull requests, and deployments

### Team Coordination

1. **Assignment Strategy**: Assign issues based on expertise and current workload
2. **Priority Management**: Use priority levels consistently across teams
3. **Communication**: Keep issue comments updated with progress and blockers
4. **Cross-team Dependencies**: Use projects to coordinate work between teams

<Warning>
  Always verify team IDs, user IDs, and state IDs using the list tools before creating or updating issues.
</Warning>

<Tip>
  **Pro Tip**: Use descriptive issue titles and markdown-formatted descriptions for better searchability and team communication.
</Tip>

***

## Guardrails

In addition to the [14 universal guardrails](/civic/concepts/guardrails), this server has **12 server-specific guardrails** across 8 operations.

| Guardrail                                  | Operation             | Timing   | Description                                                       |
| ------------------------------------------ | --------------------- | -------- | ----------------------------------------------------------------- |
| Block Issue Creation in Non-Vetted Teams   | `create_issue`        | Request  | Prevent creating issues in teams that are not vetted              |
| Block Project Creation in Non-Vetted Teams | `create_project`      | Request  | Prevent creating projects in teams that are not vetted            |
| Restrict to Vetted Project Names           | `get_project`         | Request  | Only allow queries for whitelisted Linear project names           |
| Restrict to Vetted Team Names              | `get_team`            | Request  | Only allow queries for whitelisted Linear team names              |
| Block Email Addresses in Searches          | `get_user`            | Request  | Prevent searching for users by email address                      |
| Filter Issues to Vetted Projects           | `list_issues`         | Response | Redact issues that don't belong to vetted projects                |
| Restrict to Vetted Team IDs                | `list_issue_statuses` | Request  | Only allow queries for whitelisted Linear team IDs                |
| Filter Projects to Vetted List             | `list_projects`       | Response | Redact projects that are not on the vetted list                   |
| Redact User Admin Status                   | `list_users`          | Response | Redact admin status from user data to prevent privilege discovery |
| Redact User Last Seen Status               | `list_users`          | Response | Redact last seen timestamps to protect user privacy               |
| Restrict to Vetted Project IDs             | `update_project`      | Request  | Only allow operations on whitelisted Linear project IDs           |
| Redact Workspace URLs                      | *(all operations)*    | Response | Redact Linear workspace URLs to prevent workspace enumeration     |

<Tip>
  Configure guardrails via the Civic UI or ask the Configurator Agent: "Add guardrails to my Linear server."
</Tip>