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

1. Open Linear settings

   Go to Settings → Connections → Linear. You need to be an org admin.

2. Install the workspace connection

   Click Install and authorize the Linear workspace. This connects one Linear workspace to your Capy organization.

3. Set defaults

   Choose a default project and configure branch defaults so Linear-origin tasks run with consistent routing and base branches.

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.

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

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.

Issues are landing in the wrong project

Check Team mappings first. If a team has no mapping, Capy uses the default project.

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.

I can't install or disconnect Linear

Only org admins can install, reinstall, or disconnect the org-level Linear workspace connection.