---
title: "Conector de Linear"
description: "Guía completa de integración con Linear para sincronizar issues, proyectos y datos de actividad del equipo con Brevo a través de Tajo."
url: https://tajo.io/es/docs/connectors/custom/linear/
markdown: https://tajo.io/es/docs/connectors/custom/linear.md
lang: es-ES
robots: noindex
---

Solicita acceso anticipado

Escribe tu nombre y dirección de correo de trabajo. Te enviaremos un enlace para confirmar tu solicitud de acceso a Tajo.

# Conector de Linear

Estado del conector: Planificado Aún no está construido. Tajo no ejecuta este conector hoy.

| Campo de origen | Campo de destino | Valor de ejemplo |
| --- | --- | --- |
| `record.id` | `source_id` | `record_1042` |
| `record.updated_at` | `updated_at` | `2026-10-18T08:00:00Z` |
| `record.value` | `value` | `sample_value` |

Conecta tu workspace de Linear con Brevo para el seguimiento de issues orientadas al cliente, las notificaciones de actualizaciones de producto y las campañas de hitos de desarrollo a través de Tajo.

## Resumen

| Propiedad | Valor |
| --- | --- |
| **Plataforma** | Linear |
| **Categoría** | Personalizada |
| **Complejidad de configuración** | Fácil |
| **Integración oficial** | No |
| **Datos sincronizados** | Issues, Proyectos, Usuarios, Eventos |
| **Tipo de API** | GraphQL API |
| **Autenticación** | OAuth 2.0 / Personal API Key |
| **URL base** | `https://api.linear.app/graphql` |

## Funcionalidades

- **Sincronización de eventos de issue** - Reenvía los eventos de creación, actualización y finalización de issues a las cronologías de contacto en Brevo
- **Seguimiento de hitos de proyecto** - Dispara campañas de Brevo cuando los proyectos alcancen hitos clave
- **Vinculación de issues con clientes** - Asocia issues de Linear con contactos de Brevo para la visibilidad de soporte
- **Segmentación basada en etiquetas** - Asocia las etiquetas de Linear con los atributos de contacto de Brevo
- **Analítica de ciclos** - Sincroniza datos de finalización de sprints/ciclos para informes de rendimiento del equipo
- **Automatización por webhook** - Reenvío de eventos en tiempo real mediante los webhooks de Linear

## Requisitos previos

Antes de empezar, asegúrate de tener:

1. Un workspace de Linear con acceso de administrador
2. Una Personal API key o una aplicación OAuth configurada
3. Una cuenta de Brevo con acceso a la API
4. Una cuenta de Tajo con suscripción activa

## Autenticación

Linear admite Personal API keys y OAuth 2.0.

### Opción 1: Personal API Key

1. Ve a **Linear** > **Settings** > **API** > **Personal API keys**
2. Haz clic en **Create key**
3. Ponle el nombre “Tajo Integration”
4. Copia la clave generada (empieza por `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 } }"}'
```

### Opción 2: OAuth 2.0

Para integraciones que sirven a varios workspaces:

1. Crea una aplicación OAuth en [linear.app/settings/api/applications](https://linear.app/settings/api/applications)
2. Configura la URI de redirección: `https://app.tajo.io/callbacks/linear`
3. Solicita los scopes: `read`, `write`, `issues:create`, `comments:create`

GraphQL API

Linear usa exclusivamente una GraphQL API. Todas las consultas y mutaciones pasan por un único endpoint: `https://api.linear.app/graphql`. Tajo gestiona toda la construcción de consultas GraphQL automáticamente.

### Conectar con 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
```

## Configuración

### Configuración básica

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

### Asignación de campos

Asocia los datos de usuario e issue de Linear con los atributos de 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
```

### Asignación de eventos

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

## Endpoints de la API

Linear usa un único endpoint GraphQL. Principales consultas y mutaciones usadas por Tajo:

| Operación | Tipo | Propósito |
| --- | --- | --- |
| `issues` | Query | Listar y filtrar issues |
| `issue` | Query | Obtener una issue por ID |
| `projects` | Query | Listar todos los proyectos |
| `cycles` | Query | Listar ciclos (sprints) |
| `teams` | Query | Listar equipos del workspace |
| `users` | Query | Listar miembros del workspace |
| `viewer` | Query | Obtener info del usuario autenticado |
| `issueCreate` | Mutation | Crear una issue nueva |
| `issueUpdate` | Mutation | Actualizar una issue existente |
| `commentCreate` | Mutation | Añadir un comentario a una issue |
| `webhookCreate` | Mutation | Registrar un webhook |

### Ejemplo de consulta 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
    }
  }
}
```

## Ejemplos de código

### Inicializar el conector

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

### Sincronizar issues

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

### Gestionar webhooks de Linear

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

### Crear una issue a partir de un evento de 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']
    });
  }
});
```

## Límites de velocidad

Linear aplica límites de velocidad en su API GraphQL:

| Tipo de límite | Valor |
| --- | --- |
| **Frecuencia de peticiones** | 1.500 peticiones por hora por API key |
| **Complejidad de la consulta** | 10.000 puntos de complejidad por petición |
| **Paginación** | 250 nodos máx. por página (por defecto 50) |
| **Webhooks** | Eventos entrantes ilimitados |

Presupuesto de complejidad

Linear usa un sistema de límites de velocidad basado en complejidad. Las consultas sencillas cuestan menos puntos. Tajo optimiza las consultas para minimizar la complejidad solicitando solo los campos necesarios y usando paginación eficiente.

Linear devuelve `429 Too Many Requests` con una cabecera `Retry-After` cuando se superan los límites.

## Resolución de problemas

### Problemas habituales

| Problema | Causa | Solución |
| --- | --- | --- |
| 401 Unauthorized | API key no válida o revocada | Genera una API key nueva en Linear Settings |
| Errores de consulta | Sintaxis GraphQL no válida | Valida las consultas con el explorador de API de Linear |
| Issues ausentes | Acceso de equipo restringido | Asegúrate de que el propietario de la API key tenga acceso a los equipos objetivo |
| El webhook no se dispara | URL incorrecta o deshabilitado | Revisa el estado del webhook en Linear Settings > API > Webhooks |
| Paginación incompleta | Falta el cursor `after` | Asegúrate de que la paginación itere hasta que `hasNextPage` sea false |

### Modo depuración

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

### Probar la conexión

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

## Buenas prácticas

1. **Usa webhooks para tiempo real** - Registra webhooks en lugar de hacer polling para los cambios de issues
2. **Filtra por equipo** - Sincroniza solo issues de equipos relevantes para reducir el uso de la API
3. **Optimiza las consultas GraphQL** - Solicita solo los campos necesarios para respetar los límites de complejidad
4. **Asigna etiquetas a segmentos** - Usa las etiquetas de Linear para segmentar contactos en Brevo
5. **Gestiona la paginación** - Revisa siempre `hasNextPage` y usa `endCursor` para obtener datos completos
6. **Verifica las firmas de webhook** - Valida siempre la cabecera `Linear-Signature`

## Seguridad

- **Autenticación por API key** - Claves personales limitadas al workspace
- **OAuth 2.0** - Flujo de autorización seguro para integraciones multiworkspace
- **Solo HTTPS** - Toda la comunicación con la API se cifra vía TLS 1.2+
- **Firmas de webhook** - Verificación de firma basada en HMAC
- **Almacenamiento cifrado** - API keys cifradas en reposo en Tajo
- **Cumplimiento SOC 2** - La plataforma de Linear está certificada en SOC 2 Tipo II

## Recursos relacionados

- [Conector de GitHub](https://tajo.io/es/docs/connectors/custom/github)
- [Conector de Jira](https://tajo.io/es/docs/connectors/custom/jira)
- [Conector de Notion](https://tajo.io/es/docs/connectors/custom/notion)
- [API de contactos de Brevo](https://tajo.io/es/docs/contact-management)