---
title: "Конектор Linear"
description: "Пълно ръководство за интеграция с Linear за синхронизация на issue-та, проекти и данни за активност на екипа с Brevo чрез Tajo."
url: https://tajo.io/bg/docs/connectors/custom/linear/
markdown: https://tajo.io/bg/docs/connectors/custom/linear.md
lang: bg-BG
robots: noindex
---

Заявете ранен достъп

Въведете собственото си име и служебен имейл адрес. Ще ви изпратим връзка за потвърждение на заявката за достъп до Tajo.

# Конектор Linear

Статус на конектора: Планиран Все още не е изграден. Tajo не изпълнява този конектор днес.

| Поле източник | Целево поле | Примерна стойност |
| --- | --- | --- |
| `record.id` | `source_id` | `record_1042` |
| `record.updated_at` | `updated_at` | `2026-10-18T08:00:00Z` |
| `record.value` | `value` | `sample_value` |

Свържете вашето Linear работно пространство с Brevo за проследяване на issue-та, видими за клиентите, известия за продуктови обновявания и кампании за етапи в разработката чрез Tajo.

## Преглед

| Свойство | Стойност |
| --- | --- |
| **Платформа** | Linear |
| **Категория** | Персонализирана |
| **Сложност на настройка** | Лесна |
| **Официална интеграция** | Не |
| **Синхронизирани данни** | Issue-та, проекти, потребители, събития |
| **Тип на API** | GraphQL API |
| **Автентикация** | OAuth 2.0 / Personal API Key |
| **Base URL** | `https://api.linear.app/graphql` |

## Функции

- **Синхронизация на събития за issue-та** – Препращайте събития за създаване, обновяване и завършване на issue-та към времевите линии на контактите в Brevo
- **Проследяване на етапи на проекта** – Задействайте кампании в Brevo, когато проектите достигнат ключови етапи
- **Свързване на клиентски issue-та** – Асоциирайте Linear issue-тата с контакти в Brevo за видимост на поддръжката
- **Сегментация на базата на етикети** – Мапвайте Linear етикети към атрибути на контактите в Brevo
- **Аналитика на cycle-и** – Синхронизирайте данни за завършване на sprint/cycle за отчитане на производителността на екипа
- **Автоматизация, задвижвана от webhook** – Препращане на събития в реално време чрез Linear webhooks

## Предварителни условия

Преди да започнете, уверете се, че имате:

1. Linear работно пространство с администраторски достъп
2. Personal API ключ или конфигурирано OAuth приложение
3. Акаунт в Brevo с API достъп
4. Акаунт в Tajo с активен абонамент

## Автентикация

Linear поддържа Personal API ключове и OAuth 2.0.

### Опция 1: Personal API Key

1. Отидете в **Linear** > **Settings** > **API** > **Personal API keys**
2. Щракнете върху **Create key**
3. Наименувайте го “Tajo Integration”
4. Копирайте генерирания ключ (започва с `lin_api_`)

```bash
curl -X POST https://api.linear.app/graphql \
  -H "Authorization: $LINEAR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "{ viewer { id name email } }"}'
```

### Опция 2: OAuth 2.0

За интеграции, обслужващи множество работни пространства:

1. Създайте OAuth приложение на [linear.app/settings/api/applications](https://linear.app/settings/api/applications)
2. Конфигурирайте redirect URI: `https://app.tajo.io/callbacks/linear`
3. Заявете обхвати: `read`, `write`, `issues:create`, `comments:create`

GraphQL API

Linear използва изключително GraphQL API. Всички заявки и мутации минават през една крайна точка: `https://api.linear.app/graphql`. Tajo обработва цялата GraphQL конструкция автоматично.

### Свързване към Tajo

```bash
# Using Personal API Key
tajo connectors install linear \
  --api-key $LINEAR_API_KEY

# Using OAuth
tajo connectors install linear \
  --client-id $LINEAR_CLIENT_ID \
  --client-secret $LINEAR_CLIENT_SECRET
```

## Конфигурация

### Основна настройка

```yaml
connectors:
  linear:
    enabled: true

    sync:
      issues: true
      projects: true
      cycles: true
      users: true

    teams:
      - key: "ENG"
        sync_to_list: 38
      - key: "SUPPORT"
        sync_to_list: 39

    issue_states:
      - Backlog
      - Todo
      - "In Progress"
      - Done
      - Canceled
```

### Мапване на полета

Мапвайте данни за потребители и issue-та в Linear към атрибути в Brevo:

```yaml
field_mapping:
  # User fields
  id: LINEAR_USER_ID
  email: email
  name: FIRSTNAME

  # Issue metrics mapped to contact events
  last_issue_identifier: LAST_LINEAR_ISSUE
  last_issue_state: LAST_ISSUE_STATUS
  last_issue_priority: LAST_ISSUE_PRIORITY
  total_issues: LINEAR_ISSUE_COUNT

  # Project data
  current_project: ACTIVE_PROJECT
  team_key: LINEAR_TEAM
```

### Мапване на събития

```yaml
event_mapping:
  Issue.create: ISSUE_CREATED
  Issue.update: ISSUE_UPDATED
  Issue.remove: ISSUE_DELETED
  Comment.create: COMMENT_ADDED
  Project.update: PROJECT_UPDATED
  Cycle.update: CYCLE_UPDATED
```

## API крайни точки

Linear използва една GraphQL крайна точка. Ключови заявки и мутации, използвани от Tajo:

| Операция | Тип | Цел |
| --- | --- | --- |
| `issues` | Query | Списък и филтриране на issue-та |
| `issue` | Query | Извличане на единично issue по ID |
| `projects` | Query | Списък на всички проекти |
| `cycles` | Query | Списък на cycle-ите (sprints) |
| `teams` | Query | Списък на екипите в работното пространство |
| `users` | Query | Списък на членовете на работното пространство |
| `viewer` | Query | Извличане на автентицирания потребител |
| `issueCreate` | Mutation | Създаване на ново issue |
| `issueUpdate` | Mutation | Обновяване на съществуващо issue |
| `commentCreate` | Mutation | Добавяне на коментар към issue |
| `webhookCreate` | Mutation | Регистриране на webhook |

### Пример за GraphQL заявка

```graphql
query GetIssues($filter: IssueFilter, $first: Int, $after: String) {
  issues(filter: $filter, first: $first, after: $after) {
    nodes {
      id
      identifier
      title
      state { name }
      priority
      assignee { email name }
      labels { nodes { name } }
      createdAt
      updatedAt
    }
    pageInfo {
      hasNextPage
      endCursor
    }
  }
}
```

## Примери за код

### Инициализация на конектора

```javascript
import { TajoClient } from '@tajo/sdk';

const tajo = new TajoClient({
  apiKey: process.env.TAJO_API_KEY,
  brevoApiKey: process.env.BREVO_API_KEY
});

await tajo.connectors.connect('linear', {
  apiKey: process.env.LINEAR_API_KEY
});
```

### Синхронизация на issue-та

```javascript
await tajo.connectors.sync('linear', {
  type: 'incremental',
  resources: ['issues'],
  teams: ['ENG', 'SUPPORT'],
  since: '2024-01-01'
});

const status = await tajo.connectors.status('linear');
console.log(status);
// {
//   connected: true,
//   lastSync: '2024-03-15T18:00:00Z',
//   issuesTracked: 3200,
//   projectsMonitored: 8,
//   usersLinked: 45
// }
```

### Обработка на Linear webhooks

```javascript
app.post('/webhooks/linear', async (req, res) => {
  const event = req.body;

  // Verify webhook signature
  const signature = req.get('Linear-Signature');
  if (!verifyLinearSignature(req.body, signature)) {
    return res.status(401).send('Unauthorized');
  }

  await tajo.connectors.handleWebhook('linear', {
    type: event.type,
    action: event.action,
    payload: {
      issueId: event.data?.id,
      identifier: event.data?.identifier,
      title: event.data?.title,
      state: event.data?.state?.name,
      assigneeEmail: event.data?.assignee?.email
    }
  });

  res.status(200).send('OK');
});
```

### Създаване на issue от Brevo събитие

```javascript
// Create a Linear issue when a Brevo contact submits a request
tajo.events.on('contact.event', async (event) => {
  if (event.name === 'FEATURE_REQUEST') {
    await tajo.connectors.create('linear', {
      teamId: 'ENG',
      title: `Feature Request: ${event.data.subject}`,
      description: event.data.description,
      priority: 3,
      labelIds: ['feature-request']
    });
  }
});
```

## Лимити на заявки

Linear налага лимити на заявки на своето GraphQL API:

| Тип лимит | Стойност |
| --- | --- |
| **Честота на заявките** | 1500 заявки на час за API ключ |
| **Сложност на заявката** | 10 000 точки за сложност на заявка |
| **Пагинация** | Максимум 250 nodes на страница (по подразбиране 50) |
| **Webhooks** | Неограничени входящи събития |

Бюджет за сложност

Linear използва система за rate limiting на базата на сложност. Простите заявки струват по-малко точки. Tajo оптимизира заявките за минимизиране на сложността, като заявява само нужните полета и използва ефективна пагинация.

Linear връща `429 Too Many Requests` с хедър `Retry-After` при надвишаване на лимитите.

## Отстраняване на проблеми

### Често срещани проблеми

| Проблем | Причина | Решение |
| --- | --- | --- |
| 401 Unauthorized | Невалиден или отнет API ключ | Генерирайте нов API ключ в Linear Settings |
| Грешки в заявката | Невалиден GraphQL синтаксис | Валидирайте заявките чрез Linear’s API explorer |
| Липсващи issue-та | Ограничен достъп до екипа | Уверете се, че собственикът на API ключа има достъп до целевите екипи |
| Webhook не се задейства | Грешен URL или деактивиран | Проверете статуса на webhook в Linear Settings > API > Webhooks |
| Непълна пагинация | Липсващ `after` cursor | Уверете се, че пагинацията цикли, докато `hasNextPage` стане false |

### Debug режим

```yaml
connectors:
  linear:
    debug: true
    log_level: verbose
    log_queries: true
```

### Тестване на връзката

```bash
tajo connectors test linear
# ✓ GraphQL API connection successful
# ✓ Workspace access verified
# ✓ Team list readable
# ✓ Issue query operational
# ✓ Webhook registration available
```

## Най-добри практики

1. **Използвайте webhooks за реално време** – Регистрирайте webhooks вместо допитване за промени в issue-тата
2. **Филтрирайте по екип** – Синхронизирайте само issue-та от релевантни екипи, за да намалите API употребата
3. **Оптимизирайте GraphQL заявките** – Заявявайте само нужните полета, за да останете в рамките на лимитите за сложност
4. **Мапвайте етикети към сегменти** – Използвайте Linear етикети за задвижване на сегментацията на контактите в Brevo
5. **Обработвайте пагинацията** – Винаги проверявайте `hasNextPage` и използвайте `endCursor` за пълни данни
6. **Проверявайте webhook подписите** – Винаги валидирайте хедъра `Linear-Signature`

## Сигурност

- **Автентикация с API ключ** – Лични ключове, обхванати до работно пространство
- **OAuth 2.0** – Сигурен поток за оторизация за интеграции с множество работни пространства
- **Само HTTPS** – Цялата API комуникация е криптирана чрез TLS 1.2+
- **Webhook подписи** – HMAC-базирана верификация на подписи
- **Криптирано съхранение** – API ключовете са криптирани в покой в Tajo
- **SOC 2 съответствие** – Платформата Linear е SOC 2 Type II сертифицирана

## Свързани ресурси

- [Конектор GitHub](https://tajo.io/bg/docs/connectors/custom/github)
- [Конектор Jira](https://tajo.io/bg/docs/connectors/custom/jira)
- [Конектор Notion](https://tajo.io/bg/docs/connectors/custom/notion)
- [Brevo Contacts API](https://tajo.io/bg/docs/contact-management)