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

# Linear Integration

> Connect Linear to Capy to delegate issues, route work by team mappings, and run tasks with configurable default project and branch behavior.

## Overview

Connect Linear to Capy so your team can delegate issues directly from Linear and keep execution tied to the right project and repository defaults in Capy.

## Connecting Linear

<Steps>
  <Step title="Open Linear settings">
    Go to [Settings → Connections →
    Linear](https://capy.ai/settings/org/connections/linear). You need to be an
    org admin.
  </Step>

  <Step title="Install the workspace connection">
    Click **Install** and authorize the Linear workspace. This connects one
    Linear workspace to your Capy organization.
  </Step>

  <Step title="Set defaults">
    Choose a default project and configure branch defaults so Linear-origin
    tasks run with consistent routing and base branches.
  </Step>
</Steps>

## Team and project mapping behavior

Use **Team mappings** in Linear settings to route work automatically:

1. Map a Linear team to a Capy project
2. Delegated issues from that team are created in the mapped project
3. If no team mapping exists, Capy falls back to your **Default project**

This keeps teams aligned to the right codebase without manual project selection on every issue.

## Default project and branch behavior

* **Default project**: used when a Linear team does not have an explicit mapping
* **Default branches**: set per repository for Linear-origin captain runs
* If no custom branch default is set for a repo, Capy uses the repository default branch

You can update these values anytime in [Settings → Connections → Linear](https://capy.ai/settings/org/connections/linear).

## What agents can do via Linear

When work is delegated from Linear, Capy can:

* Create and run tasks with Linear issue context
* Apply team-to-project mappings automatically
* Use configured default branches for repository work
* Use your Linear integration behavior settings (auto start, auto-create PR)
* Continue task execution from the same Linear workflow

## Permissions and scope notes

* Linear is connected at the organization level in Capy
* Installation and reconnect actions require org admin access
* Team mappings, defaults, and behavior settings are shared org configuration
* Capy uses the authorized Linear workspace for delegation and context

## Troubleshooting

<AccordionGroup>
  <Accordion title="Linear isn't connected in Capy">
    Make sure an org admin completed the install flow in Settings → Connections
    → Linear. If credentials changed, reinstall the connection.
  </Accordion>

  <Accordion title="Issues are landing in the wrong project">
    Check Team mappings first. If a team has no mapping, Capy uses the default
    project.
  </Accordion>

  <Accordion title="Tasks are using the wrong base branch">
    Review Default branches in Linear settings. If a repo-specific branch isn't
    set, Capy falls back to that repository's default branch.
  </Accordion>

  <Accordion title="I can't install or disconnect Linear">
    Only org admins can install, reinstall, or disconnect the org-level Linear
    workspace connection.
  </Accordion>
</AccordionGroup>