---
title: "Conector Linear"
description: "Guia completo de integração do Linear para sincronizar issues, projetos e dados de atividade de equipe com o Brevo via Tajo."
url: https://tajo.io/pt/docs/connectors/custom/linear/
markdown: https://tajo.io/pt/docs/connectors/custom/linear.md
lang: pt-BR
robots: noindex
---

Solicite acesso antecipado

Indique o seu nome e endereço de e-mail profissional. Enviaremos um link para confirmar o seu pedido de acesso ao Tajo.

# Conector Linear

Status do conector: Planejado Ainda não construído. O Tajo não executa este conector hoje.

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

Conecte seu workspace Linear ao Brevo para rastreamento de issues voltado ao cliente, notificações de atualização de produto e campanhas de marcos de desenvolvimento através do Tajo.

## Visão geral

| Propriedade | Valor |
| --- | --- |
| **Plataforma** | Linear |
| **Categoria** | Personalizado |
| **Complexidade de configuração** | Fácil |
| **Integração oficial** | Não |
| **Dados sincronizados** | Issues, Projetos, Usuários, Eventos |
| **Tipo de API** | GraphQL API |
| **Autenticação** | OAuth 2.0 / Personal API Key |
| **URL base** | `https://api.linear.app/graphql` |

## Recursos

- **Sincronização de eventos de issue** - Encaminhe eventos de criação, atualização e conclusão de issues para as timelines de contato do Brevo
- **Rastreamento de marcos de projeto** - Dispare campanhas do Brevo quando projetos atingirem marcos importantes
- **Vinculação de issues de clientes** - Associe issues do Linear com contatos do Brevo para visibilidade de suporte
- **Segmentação baseada em labels** - Mapeie labels do Linear para atributos de contato do Brevo
- **Analytics de ciclo** - Sincronize dados de conclusão de sprint/ciclo para relatórios de desempenho da equipe
- **Automação orientada a webhooks** - Encaminhamento de eventos em tempo real via webhooks do Linear

## Pré-requisitos

Antes de começar, certifique-se de que você tem:

1. Um workspace Linear com acesso de administrador
2. Uma Personal API key ou aplicação OAuth configurada
3. Uma conta Brevo com acesso à API
4. Uma conta Tajo com assinatura ativa

## Autenticação

O Linear suporta Personal API keys e OAuth 2.0.

### Opção 1: Personal API Key

1. Acesse **Linear** > **Settings** > **API** > **Personal API keys**
2. Clique em **Create key**
3. Nomeie como “Tajo Integration”
4. Copie a chave gerada (começa com `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 } }"}'
```

### Opção 2: OAuth 2.0

Para integrações que atendem a múltiplos workspaces:

1. Crie uma aplicação OAuth em [linear.app/settings/api/applications](https://linear.app/settings/api/applications)
2. Configure a URI de redirecionamento: `https://app.tajo.io/callbacks/linear`
3. Solicite os escopos: `read`, `write`, `issues:create`, `comments:create`

GraphQL API

O Linear usa exclusivamente uma API GraphQL. Todas as consultas e mutações passam por um único endpoint: `https://api.linear.app/graphql`. O Tajo trata a construção de consultas GraphQL automaticamente.

### Conectando ao 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
```

## Configuração

### Configuração 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
```

### Mapeamento de campos

Mapeie dados de usuário e issue do Linear para atributos do 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
```

### Mapeamento 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 da API

O Linear usa um único endpoint GraphQL. Principais consultas e mutações usadas pelo Tajo:

| Operação | Tipo | Finalidade |
| --- | --- | --- |
| `issues` | Query | Listar e filtrar issues |
| `issue` | Query | Obter issue única por ID |
| `projects` | Query | Listar todos os projetos |
| `cycles` | Query | Listar ciclos (sprints) |
| `teams` | Query | Listar equipes do workspace |
| `users` | Query | Listar membros do workspace |
| `viewer` | Query | Obter informações do usuário autenticado |
| `issueCreate` | Mutation | Criar uma nova issue |
| `issueUpdate` | Mutation | Atualizar uma issue existente |
| `commentCreate` | Mutation | Adicionar um comentário a uma issue |
| `webhookCreate` | Mutation | Registrar um webhook |

### Exemplo 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
    }
  }
}
```

## Exemplos de código

### Inicializar o 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
// }
```

### Tratar webhooks do 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');
});
```

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

## Limites de taxa

O Linear aplica limites de taxa em sua API GraphQL:

| Tipo de limite | Valor |
| --- | --- |
| **Taxa de requisição** | 1.500 requisições por hora por chave de API |
| **Complexidade de consulta** | 10.000 pontos de complexidade por requisição |
| **Paginação** | Máximo de 250 nós por página (padrão 50) |
| **Webhooks** | Eventos de entrada ilimitados |

Orçamento de complexidade

O Linear usa um sistema de limitação de taxa baseado em complexidade. Consultas simples custam menos pontos. O Tajo otimiza consultas para minimizar a complexidade solicitando apenas os campos necessários e usando paginação eficiente.

O Linear retorna `429 Too Many Requests` com um cabeçalho `Retry-After` quando os limites são excedidos.

## Solução de problemas

### Problemas comuns

| Problema | Causa | Solução |
| --- | --- | --- |
| 401 Unauthorized | Chave de API inválida ou revogada | Gere uma nova chave de API em Linear Settings |
| Erros de consulta | Sintaxe GraphQL inválida | Valide consultas usando o explorador de API do Linear |
| Issues ausentes | Acesso à equipe restrito | Garanta que o dono da chave de API tenha acesso às equipes alvo |
| Webhook não disparando | URL incorreta ou desabilitado | Verifique o status do webhook em Linear Settings > API > Webhooks |
| Paginação incompleta | Cursor `after` ausente | Garanta que a paginação iterra até `hasNextPage` ser false |

### Modo de depuração

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

### Testar conexão

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

## Melhores práticas

1. **Use webhooks para tempo real** - Registre webhooks em vez de fazer polling para mudanças de issue
2. **Filtre por equipe** - Sincronize apenas issues de equipes relevantes para reduzir o uso da API
3. **Otimize consultas GraphQL** - Solicite apenas os campos necessários para ficar dentro dos limites de complexidade
4. **Mapeie labels para segmentos** - Use labels do Linear para direcionar a segmentação de contatos do Brevo
5. **Trate a paginação** - Sempre verifique `hasNextPage` e use `endCursor` para dados completos
6. **Verifique assinaturas de webhook** - Sempre valide o cabeçalho `Linear-Signature`

## Segurança

- **Autenticação por chave de API** - Chaves pessoais com escopo para o workspace
- **OAuth 2.0** - Fluxo de autorização seguro para integrações multi-workspace
- **Somente HTTPS** - Toda comunicação com a API é criptografada via TLS 1.2+
- **Assinaturas de webhook** - Verificação de assinatura baseada em HMAC
- **Armazenamento criptografado** - Chaves de API criptografadas em repouso no Tajo
- **Conformidade SOC 2** - A plataforma Linear é certificada SOC 2 Type II

## Recursos relacionados

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