Conector Linear

Conectați spațiul de lucru Linear la Brevo pentru urmărirea problemelor vizibile clienților, notificări despre actualizările produselor și campanii pentru etape de dezvoltare prin Tajo.

Prezentare generală

Funcționalități

• Sincronizare evenimente de probleme - Transmiteți evenimentele de creare, actualizare și finalizare a problemelor în cronologiile de contact Brevo
• Urmărire etape proiect - Declanșați campanii Brevo când proiectele ating etape cheie
• Legare probleme clienți - Asociați problemele Linear cu contactele Brevo pentru vizibilitate suport
• Segmentare bazată pe etichete - Mapați etichetele Linear la atributele de contact Brevo
• Analitica ciclului - Sincronizați datele de finalizare a sprint-ului/ciclului pentru raportarea performanței echipei
• Automatizare bazată pe webhook - Redirecționare evenimente în timp real prin webhook-uri Linear

Cerințe preliminare

Înainte de a începe, asigurați-vă că aveți:

1. Un spațiu de lucru Linear cu acces de administrator
2. O Cheie API personală sau aplicație OAuth configurată
3. Un cont Brevo cu acces API
4. Un cont Tajo cu abonament activ

Autentificare

Linear suportă Chei API personale și OAuth 2.0.

Opțiunea 1: Cheie API personală

1. Accesați Linear > Settings > API > Personal API keys
2. Faceți clic pe Create key
3. Denumiți-o “Tajo Integration”
4. Copiați cheia generată (începe cu lin_api_)

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țiunea 2: OAuth 2.0

Pentru integrări care deservesc mai multe spații de lucru:

1. Creați o aplicație OAuth la linear.app/settings/api/applications
2. Configurați URI-ul de redirecționare: https://app.tajo.io/callbacks/linear
3. Solicitați scopuri: read, write, issues:create, comments:create

Conectare la Tajo

# 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

Configurare

Configurare de bază

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

Mapare câmpuri

Mapați datele utilizatorilor și problemelor Linear la atributele Brevo:

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

Mapare evenimente

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

Puncte finale API

Linear utilizează un singur punct final GraphQL. Interogări și mutații cheie utilizate de Tajo:

Exemplu de interogare 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
    }
  }
}

Exemple de cod

Inițializare conector

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

Sincronizare probleme

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

Gestionare webhook-uri Linear

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

Creare problemă din eveniment Brevo

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

Limite de rată

Linear aplică limite de rată pe API-ul său GraphQL:

Linear returnează 429 Too Many Requests cu un antet Retry-After când limitele sunt depășite.

Depanare

Probleme frecvente

Modul de depanare

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

Testare conexiune

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

Bune practici

1. Utilizați webhook-uri pentru timp real - Înregistrați webhook-uri în loc de interogare pentru modificările problemelor
2. Filtrați după echipă - Sincronizați doar problemele din echipele relevante pentru a reduce utilizarea API
3. Optimizați interogările GraphQL - Solicitați doar câmpurile necesare pentru a rămâne în limitele de complexitate
4. Mapați etichetele la segmente - Utilizați etichetele Linear pentru a conduce segmentarea contactelor Brevo
5. Gestionați paginarea - Verificați întotdeauna hasNextPage și utilizați endCursor pentru date complete
6. Verificați semnăturile webhook - Validați întotdeauna antetul Linear-Signature

Securitate

• Autentificare cu cheie API - Chei personale limitate la spațiul de lucru
• OAuth 2.0 - Flux de autorizare securizat pentru integrări cu mai multe spații de lucru
• Numai HTTPS - Toată comunicarea API criptată prin TLS 1.2+
• Semnături webhook - Verificare semnătură bazată pe HMAC
• Stocare criptată - Chei API criptate în repaus în Tajo
• Conformitate SOC 2 - Platforma Linear este certificată SOC 2 Tip II

Resurse conexe

• Conector GitHub
• Conector Jira
• Conector Notion
• API Contacte Brevo