# Linear Integration

This guide shows two ways to connect Linear to Testifly:

- **Connect With API key** if you want to use a Linear API key
- **Connect As Agent** if you want to authorize Testifly without creating or storing a Linear API key

After the connection is set up, you can use Linear issues during feature creation in Testifly. When you use **Connect As Agent**, you can also use the Testifly integration from inside Linear so you can chat with Testifly or assign tasks to it from your Linear workspace.

## 1. Choose how you want to connect Linear

Before you start, make sure you have:

- A Linear workspace that already has the team you want to connect
- Access to the issues you want Testifly to read
- Permission to either create a Linear API key or authorize the Testifly Linear app in your workspace

Use the option that best fits your setup:

- Choose **Connect With API key** when you want Testifly to use a personal or workspace API key
- Choose **Connect As Agent** when you want to authorize Testifly with Linear app access and avoid managing an API key

## 2. Connect Linear with an API key

Use this option if you prefer the original API key flow.

### Create the API key in Linear

1. Sign in to Linear.
2. Open **Settings**.
3. Open **API** or **API keys**.
4. Select **Create API key**.
5. Give the key a name that helps you recognize it later, for example `Testifly Linear Integration`.
6. Copy the generated key and store it somewhere safe for the next step.

> Keep the key private. Anyone who has the key can use the Linear workspace data that your account can access.

### Save the API key in Testifly

1. Open your project in Testifly.
2. Go to **Settings**.
3. Open **Integrations**.
4. In the **Linear** card, click **Connect With API key**.
5. Paste the **Linear API key**.
6. Choose the **Linear team** that Testifly should use for feature creation and daily reports.
7. Review the values in the final step.
8. Click **Save and check connection**.

Testifly reads the workspace details from the API key, saves the selected team, and validates that the connection works.

## 3. Connect Linear as an agent

Use this option when you want to connect Linear without an API key.

### Start the agent connection in Testifly

1. Open your project in Testifly.
2. Go to **Settings**.
3. Open **Integrations**.
4. In the **Linear** card, click **Connect As Agent**.

### Authorize Testifly in Linear

1. Sign in to Linear if you are prompted.
2. Review the Linear workspace authorization screen.
3. Approve the Testifly connection.
4. Wait for Linear to redirect you back to Testifly.

This flow connects Testifly by using Linear app authorization instead of a manually created API key.

### Finish the setup after the redirect

1. Return to **Settings -> Integrations** in Testifly if needed.
2. In the **Linear** card, click **Edit connection**.
3. Choose the **Linear team** that Testifly should use for feature creation and daily reports.
4. Review the values in the final step.
5. Click **Save and check connection**.

After that, the Linear card should show the connected workspace, selected team, and the latest connection result.

## 4. What Connect As Agent enables

When you connect Linear as an agent:

- You can use the Linear integration in Testifly without creating a separate API key
- Testifly stores the authorized Linear app connection for the project
- You can use Testifly from inside Linear app flows so you can chat with Testifly or assign tasks to it from Linear
- You can still use the same Linear-backed feature creation flow in Testifly after the team is selected

If the agent connection stops working, check these items first:

- The Linear app authorization was completed successfully
- The Linear workspace still allows the Testifly app connection
- The selected Linear workspace has the team you chose in Testifly
- The Linear account still has access to the issues you want to use

## 5. Use Linear when creating a new feature

Once Linear is connected successfully, you can create a feature in Testifly directly from Linear issues.

### Create the feature from Linear

1. Open your project in Testifly.
2. Go to **Features**.
3. Start creating a new feature.
4. Enter the **Feature URL**.
5. In the **Create From** section, choose **From Linear**.
6. In the **Linear** section, click **read from Linear**.
7. In the Linear selector dialog:
   1. Optionally select one or more Linear teams to narrow the search.
   2. Enter a search term such as an issue key, title text, or description text.
   3. Click **Search**.
   4. Click **Add** next to the Linear issue you want to connect.
   5. Click **Connect Selected Issues** to confirm your selection.
8. Save the feature.

### What happens after you select a Linear item

- The selected Linear issue key and title are used to populate the feature name
- The connected Linear issue keys are saved with the feature creation request
- Testifly can use the Linear-linked feature flow when the feature is created

## 6. Tips for a smoother Linear setup

- Use a dedicated Linear API key for Testifly if you choose the API key flow so it is easier to rotate later
- Use **Connect As Agent** if you want to avoid storing a personal API key in Testifly
- Make sure the Linear account or authorized app has access only to the teams Testifly needs
- If you revoke the API key or remove the app authorization in Linear, reconnect it again in **Settings -> Integrations -> Linear**
- If the **From Linear** option does not appear during feature creation, re-open the Linear integration and make sure the last connection check succeeded.