Linear konektor

Poveži svoj Linear radni prostor sa Brevo za praćenje problema okrenuto ka kupcima, obaveštenja o ažuriranjima proizvoda i kampanje o razvojnim prekretnicama putem Tajo.

Pregled

Karakteristike

• Sinhronizacija događaja problema - Prosleđivanje događaja kreiranja, ažuriranja i završetka problema na Brevo vremenske linije kontakata
• Praćenje prekretnica projekta - Pokretanje Brevo kampanja kada projekti dostignu ključne prekretnice
• Povezivanje problema sa kupcima - Asocijacija Linear problema sa Brevo kontaktima za vidljivost podrške
• Segmentacija zasnovana na labelama - Mapiranje Linear labela na Brevo atribute kontakta
• Analitika ciklusa - Sinhronizacija podataka o završetku sprinta/ciklusa za izveštavanje o performansama tima
• Automatizacija putem webhook-ova - Prosleđivanje događaja u realnom vremenu putem Linear webhook-ova

Preduslovi

Pre nego što započneš, proveri da imaš:

1. Linear radni prostor sa admin pristupom
2. Konfigurisani Personal API ključ ili OAuth aplikaciju
3. Brevo nalog sa API pristupom
4. Tajo nalog sa aktivnom pretplatom

Autentifikacija

Linear podržava Personal API ključeve i OAuth 2.0.

Opcija 1: Personal API ključ

1. Idi na Linear > Settings > API > Personal API keys
2. Klikni Create key
3. Nazovi ga “Tajo Integration”
4. Kopiraj generisani ključ (počinje sa 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 } }"}'

Opcija 2: OAuth 2.0

Za integracije koje opsluže više radnih prostora:

1. Kreiraj OAuth aplikaciju na linear.app/settings/api/applications
2. Konfiguriši redirect URI: https://app.tajo.io/callbacks/linear
3. Zatraži skopove: read, write, issues:create, comments:create

Povezivanje sa 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

Konfiguracija

Osnovno podešavanje

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

Mapiranje polja

Mapiranje Linear korisničkih i podataka o problemima na Brevo atribute:

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

Mapiranje događaja

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 endpointi

Linear koristi jedan GraphQL endpoint. Ključni upiti i mutacije koje koristi Tajo:

Primer GraphQL upita

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

Primeri koda

Inicijalizacija konektora

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

Sinhronizacija problema

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

Obrada Linear webhook-ova

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

Kreiranje problema iz Brevo događaja

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

Ograničenja brzine

Linear primenjuje ograničenja brzine na svom GraphQL API:

Linear vraća 429 Too Many Requests sa Retry-After headerom kada se prekorače limiti.

Rešavanje problema

Česti problemi

Debug režim

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

Testiraj vezu

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

Najbolje prakse

1. Koristi webhook-ove za real-time - Registruj webhook-ove umesto ispitivanja za promene problema
2. Filtriraj po timu - Sinhronizuj probleme samo od relevantnih timova da smanjiš korišćenje API-ja
3. Optimizuj GraphQL upite - Zahtevaj samo potrebna polja da ostaneš u granicama složenosti
4. Mapiraj labele na segmente - Koristi Linear labele za pokretanje Brevo segmentacije kontakata
5. Obradi paginaciju - Uvek proveri hasNextPage i koristi endCursor za kompletne podatke
6. Verifikuj webhook potpise - Uvek validiraj Linear-Signature header

Bezbednost

• Autentifikacija API ključem - Lični ključevi skopovani na radni prostor
• OAuth 2.0 - Bezbedan tok autorizacije za integracije sa više radnih prostora
• Samo HTTPS - Sva API komunikacija enkriptovana putem TLS 1.2+
• Webhook potpisi - Verifikacija potpisa zasnovana na HMAC
• Enkriptovano skladištenje - API ključevi enkriptovani u mirovanju u Tajo
• SOC 2 usklađenost - Linear platforma je SOC 2 Type II sertifikovana

Povezani resursi

• GitHub konektor
• Jira konektor
• Notion konektor
• Brevo Contacts API