> For the complete documentation index, see [llms.txt](https://ask.birdie.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://ask.birdie.ai/integrations-and-data-ingestion/how-to-connect-workflows-with/linear.md).

# Linear

### Overview

Workflows work with your Linear teams in two ways:

* **From an issue:** when an issue is created (or carries a chosen label), Birdie finds the customer evidence behind it and attaches a report to the issue.
* **From the opportunities:** every week Birdie checks whether an open issue already covers each opportunity customers are raising. If it does, Birdie **comments** with what is new. If it does not, Birdie **proposes a new issue** (created only after someone approves it, unless you choose otherwise).

### What Birdie will do

| Action                                                               | Where                                                                 |
| -------------------------------------------------------------------- | --------------------------------------------------------------------- |
| Search and read issues (title, description, state, labels, comments) | Only the team, project and labels you configure                       |
| Add a comment (marked "Birdie VoC · new evidence")                   | On an issue that already covers an opportunity                        |
| Create an issue                                                      | Only in the configured team (and project), with the labels you choose |
| Attach a Birdie report                                               | On the issue that triggered the workflow                              |

Birdie never deletes or edits your existing issues, and it ignores completed and canceled issues when looking for a match: if a problem returns after its issue was closed, Birdie proposes a new one.

### Requirements

* A Linear workspace.
* A Linear user for Birdie. We recommend a dedicated member such as `Birdie`, added to the team, so comments and issues appear as coming from Birdie.
* A workspace admin if API key creation is restricted in your workspace.

### Setup

{% stepper %}
{% step %}

### Add the Birdie user to the team

Invite the Birdie user to the team the workflow uses, with permission to comment and create issues. A member of that team is enough; no admin role is needed.
{% endstep %}

{% step %}

### Create a personal API key

* Sign in to Linear **as the Birdie user**.
* Open **Settings → Account → Security & access** and, under **Personal API keys**, click **New API key**.
* Name it `Birdie Workflows` and copy the key (it starts with `lin_api_`). Linear shows it only once.

If you do not see the option, a workspace admin has limited who can create keys. Ask an admin to allow it or to create the key for you.
{% endstep %}

{% step %}

### Note what Birdie needs

* **API key** from the previous step
* **Team key**, the prefix of your issue ids (for example `ENG` in `ENG-123`)
* **Project** (optional): tell your Birdie contact the project name and Birdie will look up its identifier
* **Labels** (optional): the labels an issue must have to be considered
  {% endstep %}

{% step %}

### Optional: send "issue created" events to Birdie

Only the "from an issue" workflow with an event trigger needs this. A workspace admin creates a webhook in **Settings → API → Webhooks**, with the URL Birdie gives you for the workflow and the resource type **Issues**. A scheduled variant that checks for labelled issues needs no webhook.
{% endstep %}
{% endstepper %}

### Connect to Birdie

When you set up the workflow, choose **+ New credential** in the Linear field and paste the API key. Birdie stores it encrypted and never shows it again.

If you prefer not to type it into Birdie, [share it securely](https://onetimesecret.com/en/) with your Birdie contact.

### Revoke or rotate

* Revoke the key in **Settings → Account → Security & access**. Workflows stop acting on Linear immediately.
* To rotate, create a new key and update the credential in Birdie. The workflow keeps its history.
* Removing the Birdie user from the team also stops access to that team.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://ask.birdie.ai/integrations-and-data-ingestion/how-to-connect-workflows-with/linear.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
