---
title: Linear
slug: linear
docTags: 
createdAt: 2021-12-17T14:38:54.000Z
---

# Purpose

Echoes can connect to your Linear instance and help you tag Linear issues with the intended outcomes and initiatives they contribute to. This allows you to express the purpose of work during the planning process in Linear and have related code contributions inherit these annotations, therefore reducing the labelling effort for engineers.

# Installation

Linear integration is done through the [integrations settings](https://app.echoeshq.com/admin/integrations).

![](https://api.archbee.com/api/optimize/cnN9HGi_h1eJLSFAvJkF4/bqUsJCdJWeWT8N4V-WgRY_cleanshot-2021-12-17-at-1541452x.png "Echoes integrations")

You can connect to Linear using either the OAuth flow (recommended), or providing a personal API keys generated through your Linear settings.

::Image[]{src="https://api.archbee.com/api/optimize/cnN9HGi_h1eJLSFAvJkF4/8pw9kqOmduQcM3f5wecq-_cleanshot-2021-12-17-at-1544032x.png" size="70" width="1632" height="1314" caption="Linear installation flow" position="center" showCaption="true"}

The installation is finalized by selecting the teams you wish to enable Echoes for.

::Image[]{src="https://api.archbee.com/api/optimize/cnN9HGi_h1eJLSFAvJkF4/OEcNrZummL9uVdJtCjNTG_cleanshot-2021-12-17-at-1546532x.png" size="70" width="1696" height="940" caption="Selecting Linear teams" position="center" showCaption="true"}

# How to use

Echoes creates labels on all teams on which it is enabled: one for each configured outcome and initiative (they will all be prefixed with `Echoes:`):

::Image[]{src="https://api.archbee.com/api/optimize/cnN9HGi_h1eJLSFAvJkF4/YP6V6bU5x7AfrHAXs40Se_cleanshot-2021-12-17-at-1605372x.png" size="70" width="1700" height="1146" caption="Linear issue labels created by Echoes" position="center" showCaption="true"}

You can link GitHub pull requests or GitLab merge requests to Linear issues through their branch name, the issue ID in their title, or the issue ID in their description (as described on [Linear documentation](https://linear.app/docs/github#link-prs)). When Echoes detects a link, it will directly apply the labels it finds on both the linked issue and its parent, if any.

![](https://api.archbee.com/api/optimize/cnN9HGi_h1eJLSFAvJkF4/NfNrNGkGYhxp2zvlCY0DJ_cleanshot-2021-12-17-at-1600462x.png "Echoes bot retrieves the label from a linked Linear issuee")

:::hint{type="info"}
### Labeling behavior details

- Labels are only applied when a pull request is opened, edited, or reopened. Changing the intent on a Linear ticket will not change the labels on a previously opened pull request.
- The automation only adds more labels and never removes previously existing labels from the pull request.
:::

## Contributing efforts from Linear issues

Some efforts happen outside of git, such as design work, customer support, or testing activities. Echoes makes it possible to account for those efforts as long as they exist as issues in a third-party system such as Linear.

A completed Linear issue tagged with one of the effort labels below will be accounted for as efforts in the same way a GitHub pull request or a GitLab merge request does.

![](https://api.archbee.com/api/optimize/cnN9HGi_h1eJLSFAvJkF4/w40LjsQbXberxYmbfaybk_cleanshot-2022-09-16-at-2023072x.png "Echoes effort labels in Linear")

These items can be found in [work items](https://app.echoeshq.com/activity/units) alongside GitHub pull requests and GitLab merge requests.

![](https://api.archbee.com/api/optimize/cnN9HGi_h1eJLSFAvJkF4/ZLaHnplTuBOLBLwqokEks_cleanshot-2022-09-16-at-2017342x.png "Linear issue tagged with an effort in work items")

## Frequently asked questions

### Q: Can we use Linear estimation to weight issues?

You cannot use Linear estimation feature at this time to weight issues in Echoes, for several reasons:

- They serve different purpose: estimation is a guess *before* work happens, while Echoes effort labels capture the realized load *after* the task is completed.
- Units are not naturally mapped: Linear estimation has more option than t-shirt sizing alone, which makes alignment across on the same scale systems difficult.
- A ticket being estimated does not mean that it should contribute to Echoes efforts. Most tickets will serve as context for a series of code changes, which Echoes will capture and account for through the corresponding GitHub pull requests and GitLab merge requests. The only tickets which should contribute efforts *by themselves* are those for which some amount of work happened outside of git.