Konektor Linear

Propojte svůj pracovní prostor Linear s Brevo pro sledování issues orientovaných na zákazníky, notifikace o aktualizacích produktu a kampaně k vývojovým milníkům přes Tajo.

Přehled

Funkce

• Synchronizace událostí issues – Přeposílejte události vytvoření, aktualizace a dokončení issues do časových os kontaktů Brevo
• Sledování projektových milníků – Spouštějte kampaně Brevo, když projekty dosáhnou klíčových milníků
• Propojení zákaznických issues – Přidružujte issues Linear ke kontaktům Brevo pro viditelnost podpory
• Segmentace podle štítků – Mapujte štítky Linear na atributy kontaktů Brevo
• Analýza cyklů – Synchronizujte data dokončení sprintů/cyklů pro reporting výkonu týmu
• Automatizace řízená webhooky – Přeposílání událostí v reálném čase přes webhooky Linear

Předpoklady

Než začnete, ujistěte se, že máte:

1. Pracovní prostor Linear s administrátorským přístupem
2. Nakonfigurovaný osobní API klíč nebo OAuth aplikaci
3. Účet Brevo s přístupem k API
4. Účet Tajo s aktivním předplatným

Ověření

Linear podporuje osobní API klíče a OAuth 2.0.

Možnost 1: Osobní API klíč

1. Přejděte do Linear > Settings > API > Personal API keys
2. Klikněte na Create key
3. Pojmenujte ho “Tajo Integration”
4. Zkopírujte vygenerovaný klíč (začíná 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 } }"}'

Možnost 2: OAuth 2.0

Pro integrace obsluhující více pracovních prostorů:

1. Vytvořte OAuth aplikaci na linear.app/settings/api/applications
2. Nakonfigurujte URI přesměrování: https://app.tajo.io/callbacks/linear
3. Požadujte rozsahy: read, write, issues:create, comments:create

Připojení k Tajo

# Použití osobního API klíče
tajo connectors install linear \
  --api-key $LINEAR_API_KEY

# Použití OAuth
tajo connectors install linear \
  --client-id $LINEAR_CLIENT_ID \
  --client-secret $LINEAR_CLIENT_SECRET

Konfigurace

Základní nastavení

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

Mapování polí

Mapujte data uživatelů a issues Linear na atributy Brevo:

field_mapping:
  # Pole uživatele
  id: LINEAR_USER_ID
  email: email
  name: FIRSTNAME

  # Metriky issues mapované na události kontaktů
  last_issue_identifier: LAST_LINEAR_ISSUE
  last_issue_state: LAST_ISSUE_STATUS
  last_issue_priority: LAST_ISSUE_PRIORITY
  total_issues: LINEAR_ISSUE_COUNT

  # Data projektu
  current_project: ACTIVE_PROJECT
  team_key: LINEAR_TEAM

Mapování událostí

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

Koncové body API

Linear používá jediný GraphQL koncový bod. Klíčové dotazy a mutace používané Tajo:

Příklad GraphQL dotazu

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

Příklady kódu

Inicializace konektoru

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

Synchronizace issues

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

Zpracování webhooků Linear

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

  // Ověření podpisu webhooku
  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');
});

Vytvoření issue z události Brevo

// Vytvoření issue Linear, když kontakt Brevo odešle požadavek
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']
    });
  }
});

Omezení rychlosti

Linear aplikuje omezení rychlosti na svém GraphQL API:

Linear vrací 429 Too Many Requests s hlavičkou Retry-After, když jsou překročeny limity.

Řešení problémů

Časté problémy

Režim ladění

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

Test připojení

tajo connectors test linear
# ✓ Připojení GraphQL API úspěšné
# ✓ Přístup k pracovnímu prostoru ověřen
# ✓ Seznam týmů čitelný
# ✓ Dotaz na issues funkční
# ✓ Registrace webhooků dostupná

Osvědčené postupy

1. Používejte webhooky pro real-time – Registrujte webhooky místo pollingu pro změny issues
2. Filtrujte podle týmu – Synchronizujte pouze issues z relevantních týmů ke snížení využití API
3. Optimalizujte GraphQL dotazy – Požadujte pouze potřebná pole pro dodržení limitů složitosti
4. Mapujte štítky na segmenty – Používejte štítky Linear k řízení segmentace kontaktů Brevo
5. Zpracovávejte stránkování – Vždy kontrolujte hasNextPage a používejte endCursor pro úplná data
6. Ověřujte podpisy webhooků – Vždy validujte hlavičku Linear-Signature

Zabezpečení

• Ověření API klíčem – Osobní klíče omezeny na pracovní prostor
• OAuth 2.0 – Bezpečný autorizační flow pro integrace s více pracovními prostory
• Pouze HTTPS – Veškerá komunikace API šifrována přes TLS 1.2+
• Podpisy webhooků – Ověření podpisu na bázi HMAC
• Šifrované úložiště – API klíče šifrované v klidu v Tajo
• Soulad s SOC 2 – Platforma Linear je certifikována podle SOC 2 Type II

Související zdroje

• Konektor GitHub
• Konektor Jira
• Konektor Notion
• API kontaktů Brevo