> For the complete documentation index, see [llms.txt](https://docs.arnica.io/arnica-documentation/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.arnica.io/arnica-documentation/getting-started/ticket-management/linear-integration.md).

# Linear

Connect Arnica to your Linear workspace. Once connected, you can use Linear as the issue tracker for [Manual Issue Creation](/arnica-documentation/getting-started/ticket-management/creating-issues/manual-issue-creation.md) and [Automated Issue Creation](/arnica-documentation/getting-started/ticket-management/creating-issues/automated-issue-creation.md).

## Integration Steps

### Create a dedicated service account

Arnica authenticates to Linear with an API key. An API key inherits the access of the Linear user who created it, so use a dedicated service account instead of a personal account - this ensures the integration keeps working if the original user leaves.

{% hint style="warning" %}
The service account will appear as the creator of every Linear issue Arnica opens. Name it clearly, e.g. `arnica-linear-service-account`.
{% endhint %}

1. Create a dedicated email address (e.g. `arnica-linear@yourcompany.com`). Use a shared inbox or alias so access is not tied to a specific person.
2. Invite the email to your Linear workspace and complete the account setup from the invitation email.
3. Add the service account to every Linear team that should receive Arnica issues.

{% hint style="info" %}
Arnica can only create issues in teams the service account can access. If you add a new Linear team later, add the service account to it as well.
{% endhint %}

### Create a Linear API key

1. Sign in to Linear as the **service account** - not your personal account.
2. Go to **Settings - Security & access** and create a new API key.
3. Give the key a descriptive name, e.g. `Arnica`.
4. Under **Permissions**, select **Only select permissions** and enable both **Read** and **Write**. Arnica needs **Read** to list teams, issue templates, and workflow states, and **Write** to open and update issues. **Admin** is not required.
5. Under **Team access**, make sure the key can reach every Linear team that should receive Arnica issues - either keep **All teams you have access to**, or choose **Only select teams** and select them explicitly.
6. Click **Create**, then copy the key. Linear displays it only once.

<figure><img src="/files/z7130mqHzxyWAaASgGZX" alt="Linear Create API key dialog with the Read and Write permissions enabled"><figcaption><p>Enable both Read and Write when creating the API key</p></figcaption></figure>

{% hint style="info" %}
Enabling **Write** automatically includes **Create issues** and **Create comments**.
{% endhint %}

Linear-side access is the primary requirement for issue creation. The Arnica user configuring the integration should have at least `Admin` permissions in Arnica.

### Integrate Linear with Arnica

1. In Arnica, navigate to **Admin - Integrations**.
2. Locate **Linear** under Issue Management and click **Connect**.

<figure><img src="/files/4NNXqbKK8d498FiDPjBC" alt="Linear listed under Issue Management on the Integrations page"><figcaption><p>Locate Linear under Issue Management and click Connect</p></figcaption></figure>

3. Paste the key into the **API Key** field and click **Validate**.

<figure><img src="/files/jAYJxlwNU6oGwpA56c36" alt="Linear Integration dialog with the API Key field and Validate button"><figcaption><p>Paste the Linear API key and click Validate</p></figcaption></figure>

4. Click **OK** to complete the integration.
5. If the integration was successful, the workspace will appear under the **Existing Integrations** section in Arnica.

<figure><img src="/files/MjRL7wk4PUgUYFJmucg1" alt="Linear workspace listed in the Existing Integrations table"><figcaption><p>Linear connected and listed under Existing Integrations</p></figcaption></figure>

{% hint style="info" %}
Repeat for each additional Linear workspace.
{% endhint %}

{% hint style="warning" %}
The API key cannot be edited after the integration is created. To rotate the key, remove the integration and connect it again.
{% endhint %}

## How Linear maps to issue rules

Linear uses the same **Create Issue Rule** form as Jira and ADO Boards, in both **Admin - Policies** and the **Issue Management** tab of an Arnica product. Only the terminology of the target container differs:

| Arnica field               | Jira / ADO Boards           | Linear                 |
| -------------------------- | --------------------------- | ---------------------- |
| Target container           | **Project**                 | **Team**               |
| Issue Type                 | Issue type / work item type | Linear issue template  |
| Open Status / Close Status | Workflow statuses           | Linear workflow states |

The **Team** selector is a searchable list - select the Linear team explicitly before saving the rule. **Assignee** and **Project** are optional; use **Project** to file the issues in a specific Linear project within the selected team.

<figure><img src="/files/2m2kwpHf65brxMU53RbC" alt="Create Issue rule configured with a Linear team, issue type, and status mapping"><figcaption><p>A Create Issue rule targeting a Linear team</p></figcaption></figure>

Field mapping, custom footers, and **Test Issue Creation** behave the same as they do for Jira and ADO Boards. See [Manual Issue Creation](/arnica-documentation/getting-started/ticket-management/creating-issues/manual-issue-creation.md) and [Automated Issue Creation](/arnica-documentation/getting-started/ticket-management/creating-issues/automated-issue-creation.md) for the full configuration steps.

{% hint style="info" %}
As with all issue management integrations, Arnica is the source of truth for finding resolution. Arnica transitions the Linear issue to the configured close status when the finding is resolved, but closing a Linear issue manually does not resolve the finding in Arnica. See [How Arnica manages the full issue lifecycle](/arnica-documentation/getting-started/ticket-management.md#how-arnica-manages-the-full-issue-lifecycle).
{% endhint %}

## Remove a Linear Integration

1. Navigate to **Admin - Integrations**.
2. Find the Linear workspace you want to remove.
3. Click the **trash icon** next to the workspace.
4. Confirm the removal.

{% hint style="warning" %}
Disconnecting stops future issue creation but does not delete existing Linear issues created by Arnica.
{% endhint %}