---
title: "Connettore Linear"
description: "Guida completa all'integrazione di Linear per sincronizzare issue, progetti e dati di attività del team con Brevo tramite Tajo."
url: https://tajo.io/it/docs/connectors/custom/linear/
markdown: https://tajo.io/it/docs/connectors/custom/linear.md
lang: it-IT
robots: noindex
---

Richiedi l’accesso anticipato

Inserisci il tuo nome e indirizzo email aziendale. Ti invieremo un link per confermare la richiesta di accesso a Tajo.

# Connettore Linear

Stato del connettore: Pianificato Non ancora realizzato. Oggi Tajo non esegue questo connettore.

| Campo di origine | Campo di destinazione | Valore di esempio |
| --- | --- | --- |
| `record.id` | `source_id` | `record_1042` |
| `record.updated_at` | `updated_at` | `2026-10-18T08:00:00Z` |
| `record.value` | `value` | `sample_value` |

Collega il tuo workspace Linear a Brevo per il tracciamento delle issue rivolte al cliente, le notifiche sugli aggiornamenti di prodotto e campagne sulle milestone di sviluppo tramite Tajo.

## Panoramica

| Proprietà | Valore |
| --- | --- |
| **Piattaforma** | Linear |
| **Categoria** | Custom |
| **Complessità di setup** | Facile |
| **Integrazione ufficiale** | No |
| **Dati sincronizzati** | Issue, Progetti, Utenti, Eventi |
| **Tipo di API** | GraphQL API |
| **Autenticazione** | OAuth 2.0 / Personal API Key |
| **Base URL** | `https://api.linear.app/graphql` |

## Funzionalità

- **Sync eventi issue** - Inoltra eventi di creazione, aggiornamento e completamento issue sulle timeline dei contatti Brevo
- **Tracciamento milestone di progetto** - Attiva campagne Brevo quando i progetti raggiungono milestone chiave
- **Collegamento issue cliente** - Associa le issue Linear ai contatti Brevo per la visibilità sul supporto
- **Segmentazione basata su label** - Mappa le label Linear sugli attributi dei contatti Brevo
- **Analytics sui cycle** - Sincronizza i dati di completamento sprint/cycle per il reporting sulle performance del team
- **Automazione via webhook** - Inoltro eventi in real-time tramite webhook Linear

## Prerequisiti

Prima di iniziare, assicurati di avere:

1. Un workspace Linear con accesso admin
2. Una Personal API key o un’applicazione OAuth configurata
3. Un account Brevo con accesso API
4. Un account Tajo con abbonamento attivo

## Autenticazione

Linear supporta Personal API key e OAuth 2.0.

### Opzione 1: Personal API Key

1. Vai su **Linear** > **Settings** > **API** > **Personal API keys**
2. Clicca su **Create key**
3. Nominala “Tajo Integration”
4. Copia la chiave generata (inizia con `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 } }"}'
```

### Opzione 2: OAuth 2.0

Per integrazioni che servono più workspace:

1. Crea un’applicazione OAuth su [linear.app/settings/api/applications](https://linear.app/settings/api/applications)
2. Configura la redirect URI: `https://app.tajo.io/callbacks/linear`
3. Richiedi gli scope: `read`, `write`, `issues:create`, `comments:create`

GraphQL API

Linear usa esclusivamente un’API GraphQL. Tutte le query e le mutation passano da un singolo endpoint: `https://api.linear.app/graphql`. Tajo gestisce automaticamente tutta la costruzione delle query GraphQL.

### Connessione a Tajo

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

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

## Configurazione

### Setup di base

```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
```

### Mapping dei campi

Mappa i dati utente e issue Linear sugli attributi Brevo:

```yaml
field_mapping:
  # Campi utente
  id: LINEAR_USER_ID
  email: email
  name: FIRSTNAME

  # Metriche issue mappate su eventi di contatto
  last_issue_identifier: LAST_LINEAR_ISSUE
  last_issue_state: LAST_ISSUE_STATUS
  last_issue_priority: LAST_ISSUE_PRIORITY
  total_issues: LINEAR_ISSUE_COUNT

  # Dati progetto
  current_project: ACTIVE_PROJECT
  team_key: LINEAR_TEAM
```

### Mapping degli eventi

```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
```

## Endpoint API

Linear usa un singolo endpoint GraphQL. Query e mutation principali usate da Tajo:

| Operazione | Tipo | Scopo |
| --- | --- | --- |
| `issues` | Query | Elenca e filtra issue |
| `issue` | Query | Ottieni una singola issue per ID |
| `projects` | Query | Elenca tutti i progetti |
| `cycles` | Query | Elenca i cycle (sprint) |
| `teams` | Query | Elenca i team del workspace |
| `users` | Query | Elenca i membri del workspace |
| `viewer` | Query | Ottieni info sull’utente autenticato |
| `issueCreate` | Mutation | Crea una nuova issue |
| `issueUpdate` | Mutation | Aggiorna una issue esistente |
| `commentCreate` | Mutation | Aggiungi un commento a una issue |
| `webhookCreate` | Mutation | Registra un webhook |

### Esempio di query 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
    }
  }
}
```

## Esempi di codice

### Inizializzare il connettore

```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
});
```

### Sincronizzare le 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
// }
```

### Gestire i webhook Linear

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

  // Verifica la firma del webhook
  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');
});
```

### Creare una issue da un evento Brevo

```javascript
// Crea una issue Linear quando un contatto Brevo invia una richiesta
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']
    });
  }
});
```

## Limiti di rate

Linear applica limiti di rate sulla sua API GraphQL:

| Tipo di limite | Valore |
| --- | --- |
| **Rate di richieste** | 1.500 richieste all’ora per API key |
| **Complessità query** | 10.000 punti di complessità per richiesta |
| **Paginazione** | Max 250 nodi per pagina (default 50) |
| **Webhook** | Eventi in ingresso illimitati |

Budget di complessità

Linear usa un sistema di rate limit basato sulla complessità. Le query semplici costano meno punti. Tajo ottimizza le query per minimizzare la complessità richiedendo solo i campi necessari e usando paginazione efficiente.

Linear restituisce `429 Too Many Requests` con un header `Retry-After` quando i limiti vengono superati.

## Risoluzione dei problemi

### Problemi comuni

| Problema | Causa | Soluzione |
| --- | --- | --- |
| 401 Unauthorized | API key non valida o revocata | Genera una nuova API key nelle impostazioni Linear |
| Errori di query | Sintassi GraphQL non valida | Valida le query con l’API explorer di Linear |
| Issue mancanti | Accesso al team limitato | Assicurati che il proprietario dell’API key abbia accesso ai team target |
| Webhook non scatta | URL errato o disabilitato | Controlla lo stato del webhook in Linear Settings > API > Webhooks |
| Paginazione incompleta | Cursor `after` mancante | Assicurati che il loop di paginazione continui finché `hasNextPage` è false |

### Modalità debug

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

### Testare la connessione

```bash
tajo connectors test linear
# ✓ Connessione API GraphQL riuscita
# ✓ Accesso al workspace verificato
# ✓ Lista team leggibile
# ✓ Query issue operativa
# ✓ Registrazione webhook disponibile
```

## Best practice

1. **Usa i webhook per il real-time** - Registra webhook invece di effettuare polling per i cambi sulle issue
2. **Filtra per team** - Sincronizza solo le issue dei team rilevanti per ridurre l’uso dell’API
3. **Ottimizza le query GraphQL** - Richiedi solo i campi necessari per restare entro i limiti di complessità
4. **Mappa le label sui segmenti** - Usa le label Linear per guidare la segmentazione dei contatti Brevo
5. **Gestisci la paginazione** - Controlla sempre `hasNextPage` e usa `endCursor` per dati completi
6. **Verifica le firme webhook** - Valida sempre l’header `Linear-Signature`

## Sicurezza

- **Autenticazione API Key** - Chiavi personali limitate al workspace
- **OAuth 2.0** - Flusso di autorizzazione sicuro per integrazioni multi-workspace
- **Solo HTTPS** - Tutte le comunicazioni API cifrate tramite TLS 1.2+
- **Firme webhook** - Verifica firma basata su HMAC
- **Archiviazione cifrata** - API key cifrate a riposo in Tajo
- **Conformità SOC 2** - La piattaforma Linear è certificata SOC 2 Type II

## Risorse correlate

- [Connettore GitHub](https://tajo.io/it/docs/connectors/custom/github)
- [Connettore Jira](https://tajo.io/it/docs/connectors/custom/jira)
- [Connettore Notion](https://tajo.io/it/docs/connectors/custom/notion)
- [Brevo Contacts API](https://tajo.io/it/docs/contact-management)